Retrieve user information
You can check the endpoints and methods that a particular user is authorized to access.
URL
GET https:<IP-address-of-SPS>/api/user_info
Sample request
The following command retrieves user information from SPS about the logged in user, using the session ID received during the authentication.
curl --cookie cookies https://<IP-address-of-SPS>/api/user_info
This information is also available on the /api/user/info and /api/userinfo endpoints.
Response
The following is a sample response received if the request to retrieve user information is successful.
{
"user": {
"name": "admin",
}
"endpoints": [
{
"methods": [
"DELETE",
"GET",
"POST",
"PUT"
],
"url": "/api"
},
{
"...": "..."
}
],
"meta": {
"href": "/api/user_info",
"...": "..."
}
}
user |
|
|
Top-level element, contains the details of the user whose access rights information has been retrieved. |
|
name |
string |
The username of the logged-in user whose information has been retrieved. |
endpoints |
|
|
Top-level element, contains the details of the endpoints that the user is authorized to access. |
|
methods |
string |
The methods that user is authorized to use, and the permitted HTTP method (for example, GET, POST) for each endpoint. This information is also available on the /api/endpoints endpoint. |
|
url |
string |
The resource that the user is authorized to access. |
200 |
OK |
User information 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. |
Checking the transaction status
Before changing anything in the configuration of SPS, you must POST a request to open a transaction.
URL
GET https:<IP-address-of-SPS>/api/transaction/
Sample request
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
Response
The following is a sample response received if opening the transaction is successful.
{
"key": "transaction",
"meta": {
"href": "/api/transaction",
"parent": "/api"
},
"transaction": {
"status": "closed"
}
}
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 |
Open a transaction
The REST API of SPS manages the changes of the configuration in transaction. You can open a transaction with a POST request, but the first change of the configuration will open the transaction automatically. For details about the transaction model of SPS see How to configure SPS using REST.
URL
POST https:<IP-address-of-SPS>/api/transaction
POST body
Note that you must:
Otherwise the SPS REST server returns a 411 - Length Required error.
Sample request
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
Response
The following is a sample response received if opening the transaction is successful.
{
"meta": {
"href": "/api/transaction",
"parent": "/api"
}
}
After opening a transaction successfully, the transaction status changes to open.
{
"body": {
"commit_message": "optional|required"
"status": "open"
},
"key": "transaction",
"meta": {
"changes": "/api/transaction/changes",
"href": "/api/transaction",
"parent": "/api"
}
}
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. |
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 POST method to open a transaction. |
409 |
WebGuiOrRpcApiConfigInProgress |
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. |
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. |
Commit a transaction
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.
URL
PUT https:<IP-address-of-SPS>/api/transaction
PUT body
The PUT request must include the following JSON object in its body.
{
"status": "commit"
}
If the Users & Access Control > 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 Users & Access Control > Configuration History page of the SPS web interface. Note that on the Users & Access Control > Configuration History page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.
{
"status": "commit",
"message": "My commit message"
}
Sample request
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
Response
The following is a sample response received if committing the transaction is successful.
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"
}
}
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. |
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 PUT method to commit a transaction. |