Before changing anything in the configuration of SPS, you must POST a request to open a transaction.
For details about the transaction model of SPS see How to configure SPS using REST.
To check the configuration changes you made in the transaction, see Reviewing the changelog of a transaction.
GET https:<IP-address-of-SPS>/api/transaction/
The following command retrieves the transaction status of SPS, using the session ID received during the authentication.
curl --cookie cookies https://<IP-address-of-SPS>/api/transaction
The following is a sample response received if opening the transaction is successful.
For details of the meta object, see Message format.
{ "key": "transaction", "meta": { "href": "/api/transaction", "parent": "/api" }, "transaction": { "status": "closed" } }
Element | Type | Description | |
---|---|---|---|
transaction | Top level element, contains the details of the current transaction | ||
status | string | The status of the current transaction. By default, or after a successful commit it is closed. After successfully opening a transaction, it is open |
Before changing anything in the configuration of SPS, you must POST a request to open a transaction. For details about the transaction model of SPS see How to configure SPS using REST.
Note that opening a transaction locks the configuration of SPS similarly to accessing SPS from the web interface. For details, see "Multiple users and locking" in the Administration Guide.
POST https:<IP-address-of-SPS>/api/transaction
Cookie name | Description | Required | Values |
---|---|---|---|
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 details on authentication, see Authenticate to the SPS REST API. Note that 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). |
Note that you must:
either send an empty body in the POST request,
or include a Content-Length: 0 header.
Otherwise the SPS REST server returns a 411 - Length Required error.
The following command opens a new transaction on SPS, using the session ID received during the authentication.
curl -X POST --data "" --cookie cookies https://<IP-address-of-SPS>/api/transaction
The following is a sample response received if opening the transaction is successful.
For details of the meta object, see Message format.
{ "meta": { "href": "/api/transaction", "parent": "/api" } }
After opening a transaction successfully, the transaction status changes to open.
{ "body": { "status": "open" }, "key": "transaction", "meta": { "changes": "/api/transaction/changes", "href": "/api/transaction", "parent": "/api" } }
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.
Code | Description | Notes |
---|---|---|
200 | OK | Transaction opened 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. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
405 | MethodNotAllowed | You tried using an unsupported HTTP method. Use the POST method to open a transaction. |
409 | WebGuiOrRpcApiConfigInProgress | The configuration of SPS is locked. Opening 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. |
411 | UnsupportedMethod | You must send a body (which can be empty) in this POST request, otherwise the SPS REST server returns a 411 - Length Required error. |
To submit your changes to SPS, you have to commit the transaction by using a PUT request with a JSON object. For details about the transaction model of SPS, see How to configure SPS using REST.
PUT https:<IP-address-of-SPS>/api/transaction
Cookie name | Description | Required | Values |
---|---|---|---|
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 details on authentication, see Authenticate to the SPS REST API. Note that 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). |
The PUT request must include the following JSON object in its body.
{ "status": "commit" }
If the AAA > Settings > Accounting settings > Require commit log option is selected in the SPS web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the SPS web interface. Note that on the AAA > Accounting page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.
{ "status": "commit", "message": "My commit message" }
The following command commits a transaction to SPS, using the session ID received during the authentication.
curl -d '{"status": "commit","message": "My commit message"}' --cookie cookies -X PUT https://<IP-address-of-SPS>/api/transaction
The following is a sample response received if committing the transaction is successful.
For details of the meta object, see Message format.
After a successful commit, the transaction status changes to closed. To make other changes, you have to open a new transaction.
{ "meta": { "href": "/api/transaction", "parent": "/api" }, "key": "transaction", "transaction": { "status": "closed" } }
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.
Code | Description | Notes |
---|---|---|
200 | OK | Transaction committed 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. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
405 | MethodNotAllowed | You tried using an unsupported HTTP method. Use the PUT method to commit a transaction. |
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.
DELETE https:<IP-address-of-SPS>/api/transaction
Cookie name | Description | Required | Values |
---|---|---|---|
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 details on authentication, see Authenticate to the SPS REST API. Note that 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). |
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
The following is a sample response received if deleting the transaction is successful.
For details of the meta object, see Message format.
{ "meta": { "href": "/api/transaction", "parent": "/api" } }
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.
Code | Description | Notes |
---|---|---|
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. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
405 | MethodNotAllowed | You tried using an unsupported HTTP method. Use the DELETE method to reset a transaction. |
© 2024 One Identity LLC. ALL RIGHTS RESERVED. Feedback Terms of Use Privacy Cookie Preference Center