To delete your changes, you have to delete the transaction. This is similar to the rollback transaction in SQL. For details about the transaction model of SPS, see How to configure SPS using REST. Deleting the transaction also deletes the configuration lock of SPS.
URL
DELETE https:<IP-address-of-SPS>/api/transaction
Cookies
session_id |
Contains the authentication token of the user |
Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For more information on authentication, see Authenticate to the SPS REST API.
NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
Sample request
The following command deletes a transaction, reverting the configuration to the state it was in when the transaction was opened, or to the current configuration available on SPS (if another user has modified it since you opened the transaction).
curl --cookie cookies -X DELETE https://<IP-address-of-SPS>/api/transaction
Response
The following is a sample response received if deleting the transaction is successful.
For more information on the meta object, see Message format.
{
"meta": {
"href": "/api/transaction",
"parent": "/api"
}
}
Status and error codes
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
200 |
OK |
Transaction deleted successfully. |
401 |
Unauthenticated |
The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
403 |
Unauthorized |
The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
405 |
MethodNotAllowed |
You tried using an unsupported HTTP method. Use the DELETE method to reset a transaction. |
To review your changes, retrieve the changelog of the transaction. For details about the transaction model of SPS, see How to configure SPS using REST.
URL
GET https:<IP-address-of-SPS>/api/transaction/changes
Cookies
session_id |
Contains the authentication token of the user |
Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For more information on authentication, see Authenticate to the SPS REST API.
NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
Sample request
The following command retrieves the changelog of the transaction.
curl --cookie cookies https://<IP-address-of-SPS>/api/transaction/changes
Response
The response contains the list of changes performed in the transaction, as list of JSON objects. Every change has a type and a path, other elements depend on the type of the transaction. For example, when you delete an object, the changelog includes the deleted object in the old_value field.
new_order |
list |
The new order of a list after the change. This field is available for reorder transactions. |
new_value |
string or JSON object |
The value of the object after the change. For example, the new value of a parameter. |
old_order |
string or JSON object |
The order of a list before the change. This field is available for reorder transactions. |
old_value |
string or JSON object |
The value of the object before the change. For example, the value of a deleted object. |
path |
string |
Path of the changed endpoint or object. |
type |
string |
The type of the change. One of: create, delete, reorder, replace |
The following is a sample response received if the changelog is empty.
{
"meta": {
"href": "/api/transaction/changes",
"parent": "/api/transaction",
"transaction": "/api/transaction"
},
"changes": []
}
The following is a sample changelog received after deleting a Channel policy.
{
"meta": {
"href": "/api/transaction/changes",
"parent": "/api/transaction",
"transaction": "/api/transaction"
},
"changes": [
{
"old_value": {
"name": "deny",
"rules": []
},
"path": "/api/configuration/ssh/channel_policies/94615110156697e93121f3",
"type": "delete"
}
]
}
Status and error codes
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
200 |
OK |
Transaction changelog has been retrieved successfully. |
401 |
Unauthenticated |
The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
403 |
Unauthorized |
The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
405 |
MethodNotAllowed |
You tried using an unsupported HTTP method. Use the GET method to retrieve the changelog a transaction. |
You can use the ?defaults query parameter to get information about all default configuration values under /api/configuration. You can include this parameter in either a POST or a PUT request with a partial request body which contains only a few configuration fields, and then the API will respond with a configuration object which shows how the API would complete the partial request body with default values.
URL
https://<IP-address-of-SPS>/api/configuration/example?defaults
Cookies
session_id |
Contains the authentication token of the user |
Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For more information on authentication, see Authenticate to the SPS REST API.
NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
Operations
POST |
/api/configuration/example?defaults |
Listing the default parameters of a resource before creating it |
|
PUT |
/api/configuration/example/resource?defaults |
Listing the default parameters of a resource before modifying it |
|
Sample request
Querying the default values for singleton resources, for example syslog servers request.
curl --cookie cookies --request PUT --data '@-' https://<IP-address-of-SPS>/api/configuration/management/syslog?defaults <<'REQUEST' |
{ |
"receivers": [ |
{} |
] |
} |
REQUEST |
Sample response
{ |
"body": { |
"encryption": { |
"client_authentication": null, |
"trust_store": null |
}, |
"include_node_id": true, |
"receivers": [ |
{ |
"address": { |
"selection": "ip", |
"value": "127.0.0.1" |
}, |
"port": 1, |
"protocol": { |
"ip_protocol": "tcp", |
"protocol_type": "legacy-bsd", |
"tls_enabled": false |
} |
} |
] |
}, |
"key": "syslog", |
"meta": { |
"first": "/api/configuration/management/accounting", |
"href": "/api/configuration/management/syslog", |
"last": "/api/configuration/management/web_gateway_authentication", |
"next": "/api/configuration/management/system_backup", |
"parent": "/api/configuration/management", |
"previous": "/api/configuration/management/support_info", |
"transaction": "/api/transaction" |
} |
} |
For more information on syslog servers, see Syslog server settings.
For more information on the meta object, see Message format.
Sample request
Querying defaults for objects in a container, for example SSH authentication policies.
curl --cookie cookies --request POST --data '@-' https://<IP-address-of-SPS>/api/configuration/ssh/authentication_policies?defaults <<'REQUEST' |
{ |
"backend": { |
"selection": "radius" |
} |
} |
REQUEST |
Sample response
{ |
"body": { |
"backend": { |
"authentication_protocol": "pap", |
"selection": "radius", |
"servers": [ |
{ |
"address": { |
"selection": "ip", |
"value": "127.0.0.1" |
}, |
"port": 1, |
"shared_secret": { |
"key": "", |
"meta": { |
"href": "/api/configuration/passwords" |
} |
} |
} |
] |
}, |
"gateway_methods": { |
"kerberos": false, |
"password": false, |
"public_key": false |
}, |
"name": "unknown", |
"relayed_methods": { |
"kerberos": false, |
"keyboard_interactive": true, |
"password": true, |
"public_key": { |
"selection": "agent" |
} |
} |
}, |
"key": "", |
"meta": { |
"first": "/api/configuration/ssh/authentication_policies", |
"href": "/api/configuration/ssh/authentication_policies", |
"last": "/api/configuration/ssh/settings_policies", |
"next": "/api/configuration/ssh/channel_policies", |
"parent": "/api/configuration/ssh", |
"previous": null, |
"transaction": "/api/transaction" |
} |
} |
For more information on SSH authentication policies, see SSH authentication policies.
For more information on the meta object, see Message format.
In addition to the standard HTTP status codes, in certain cases, the SPS REST server provides additional information in the response about the error. The following table contains a brief description of such errors. For more details, see the error object in the response body.
400 |
InvalidRequestBody |
The request body sent by the user has an invalid format. This may be an error with the encoding or the body is not a properly encoded JSON value. |
400 |
ConfigTreeNotAvailable |
An error occurred while preparing the configuration tree for the REST API. |
400 |
SyntacticError |
A value to be set is not accepted syntactically. The details section contains the path that was found to be invalid. |
400 |
InvalidPath |
The path provided by the client contains a syntax error. Path components are restricted to contain only lowercase alphanumeric characters, the dash (-) and the underscore (_) characters. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
400 |
SemanticError |
The configuration contains semantic errors, inconsistencies or other problems that would put the system into an unreliable state if the configuration had been applied. The details section contains the errors that were found in the configuration. |
401 |
Unauthenticated |
The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
401 |
AuthenticationFailure |
Authenticating the user with the given credentials has failed. |
403 |
Unauthorized |
The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
404 |
NodeNotFound |
The requested endpoint does not exist in the configuration. The details section contains the path that you tried to access, but could not be retrieved. |
404 |
NodeNotAvailable |
The requested endpoint exists in the configuration, however, it is not available directly. The details section contains the path that you tried to access, but could not be retrieved. |
405 |
MethodNotAllowed |
An attempt was made to change a configuration subtree in an unsupported way. The method <method> is not allowed for this node. |
409 |
MidAirCollisionSemanticError |
This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would interfere semantically with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction. |
409 |
WebGuiOrConsoleConfigInProgress |
The configuration of SPS is locked. Committing a new transaction is not allowed while another user is modifying configuration through interfaces other than the REST API. For example, web GUI, console, and so on. |
409 |
MidAirCollision |
This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would overwrite or interfere with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction. |
409 |
NoTransaction |
An attempt was made to change the configuration when no transaction was open. |
409 |
DoubleTransaction |
This error is returned when the client attempts to open a transaction while another transaction of that client is already started. |
417 |
Expectation Failed |
If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option. |
500 |
CommitMessageMissing |
This error is returned when a commit message is required for committing a transaction, but it was not provided in the commit request. |
500 |
TransactionCommitError |
Unexpected internal errors during committing a transaction are interpreted as TransactionCommitError. |
500 |
AuthorizationError |
The request could not be authorized due to an unexpected internal error. |