4 4 3 Tigon:Using SEP sesam REST API
Overview
SEP sesam 4.4.3 Tigon is shipped with a REST API, which is used for communication between the SEP sesam Clients and the SEP sesam Server. The API provides methods for accessing SEP sesam Server information and functionality. If the SEP sesam Server is running, the REST API can be accessed via the following base URL:
http://<host>:<port>/sep/api/
If the port is omitted, the port 11401 is used by default for all remote connections. The final part of the URL is the <resource-name>. This is the actual REST API resource itself that determines what response you will receive. To get help on SEP sesam REST API, open the URL http://<host>:<port>/sep/api/ with a web browser.
The REST API uses JSON exclusively as the input and output format, including error responses. This means that all submitted data has to be a valid JSON object (www.json.org).
Note: Most of the REST API resources are accessible only after authenticating to the SEP sesam server.
SEP sesam supports the following standard HTTP access methods for the REST API:
- GET: Retrieve current state data. It provides information about SEP sesam environment, its components, and functionality.
- POST: Create or update entities.
In example, you can get the server information by invoking a GET on http://<host>:<port>/sep/api/server/getInfo
$> curl -s --header Accept:application/json --header Content-Type:application/json;charset=UTF-8 http://sesam-srv:11401/sep/api/server/getInfo { "name" : "sesam-srv", "os" : "Linux", "id" : "V4.4 Build 3 R a7d8002", ... }
For more details on using different access methods, see section REST API usage below.
Authentication
SEP sesam uses the authentication module to grant and restrict access to SEP sesam Server. The access to REST API is only available after you have configured the authentication and grant appropriate permissions to the users. Authenticated users must be registered as one of the SEP sesam user types (admin, operator or restore). By default, after the initial installation of SEP sesam the User Permissions list does not contain any users. You need to configure the authentication module and add them; for details, see About Authentication and Authorization.
If a user does not log in or does not have the appropriate permissions, most of the SEP sesam REST API cannot be accessed.
Authentication to the API can be performed via:
- Session-based authentication
- HTTP basic authentication that creates a new session for each call
Session-based authentication
This authentication method is recommended when executing multiple API calls in a row. The POST Login API is used for session-based authentication; to create a session, a client or script have to log in to the SEP sesam Server.
- Request
- To login, call the
server/login
API by providing a user name and password as a parameter.
POST /sep/api/server/login ["<user_name>", "<password>"]
If your credentials are correct, a session ID is generated. If the credentials are not valid, an error response is issued.
- Session ID
- The ID is an alphanumerical string that must be passed to the SEP sesam Server via the X-SEP-Session header in the subsequent request.
- Logout
- Once you have finished with your work, you have to close the session by logging out from the SEP sesam Server. To log out, call the
server/logout
API and pass the session ID via the X-SEP-Session header.
GET /sep/api/server/logout
- Example
- The following script shows the usage of the session-based authentication method.
#!/bin/bash APIURL="<your server>:11401" LOGOPTS="" # headers: ACCEPT="Accept:application/json" CONTENT="Content-Type:application/json;charset=UTF-8" PRETTY="X-Output:pretty"
HEADERS="--header $ACCEPT" HEADERS="$HEADERS --header $CONTENT" # # Log in to the server – a new session is started # URL="$APIURL/server/login" PARAMS="[\"invalid\",\"\"]" echo -n "Log in to server $APIURL ... " RESPONSECODE=`curl -s $LOGOPTS $HEADERS --data $PARAMS $URL` if [ -n "`echo $RESPONSECODE | grep 'credentials.invalid'`" ]; then echo "FAILED" echo "Cause: `echo $RESPONSECODE | jq '.message'`" exit 1 else echo "SUCCESS" fi SESSIONID="X-SEP-Session:$RESPONSECODE" HEADERS="$HEADERS --header $SESSIONID" # # Query the session information # URL="$APIURL/server/getSession" echo "" echo "Get session information from server $APIURL..." curl -s $LOGOPTS $HEADERS --header $PRETTY $URL echo "" # # Log out from the server – the session will be closed # URL="$APIURL/server/logout" echo "" echo -n "Log out from server $APIURL ... " RESPONSECODE=`curl -s $LOGOPTS $HEADERS $URL` if [ "$RESPONSECODE" = "true" ]; then echo "SUCCESS" else echo "FAILED" exit 1 fi exit 0
HTTP basic authentication
This authentication method can be used when making single API calls, i.e., when using curl from command line to test the API. Basic authentication is a standard HTTP header with the username and password encoded in a variant of Base64; the encoded credentials are attached to the request via the Authorization: Basic <encoded credentials> HTTP header.
The authorization consists of the following:
- A username and password are passed as a string, separated by colon: username:password
- The resulting string is encoded using the RFC2045-MIME variant of 'Base64' (not limited to 76 char/line).
- The authorization method is specified before the encoded string, e.g.:
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
When this method is used over plain HTTP, it transmits the usernames and passwords in plain text on every request without providing any confidentiality protection for the transmitted credentials.
Note | |
|
REST API usage
The following functions are available for most API types:
Function | Pattern/Sample (curl) | Description |
list all available |
GET /sep/api/[TYPE] curl -H "X-Output: pretty" http://<host>:<port>/sep/api/operSystems |
|
list with a filter |
POST /sep/api/[TYPE]/filter curl -X POST -d "[{ \"operSystems\":[{\"name\":\"Windows Server 2008 R2\"}] }]" \ http://<host>:<port>/sep/api/clients/filter |
The filter object definition can be found in the API documentation. |
get single element |
GET /sep/api/[TYPE]/[ID] curl -H "X-Output: pretty" http://<host>:<port>/sep/api/clients/116 |
For some types, the ID is a number, in other cases it is the name. See the API documentation for more information. |
create an element |
POST /sep/api/[TYPE] curl http://<host>:<port>/sep/api/clients/116 > client-116.json (edit file) curl -X POST -d @client-116.json http://<host>:<port>/sep/api/clients |
|
update an element |
POST /sep/api/[TYPE]/[PK] curl http://<host>:<port>/sep/api/clients/116 > client-116.json (edit file) curl -X POST -d @client-116.json http://<host>:<port>/sep/api/clients/116 |
When changing a resource, make sure to always post the whole object (with the changed values). If you do not post the attributes, a request is handled the same as if it would be set to "null". |
remove an element |
GET /sep/api/[TYPE]/[ID]/delete curl http://<host>:<port>/sep/api/clients/123/delete |
Errors are also displayed in JSON format, i.e.,
{"result":"error", "error":"invalid.value", "message": "Parameter id is invalid."}
Output modifiers
You can modify the JSON output in a request by adding headers to the request:
Parameter | Pattern/Sample (curl) | Description |
Pretty print output |
X-Output: pretty curl -H "X-Output: pretty" http://localhost:11403/sep/api/operSystems |
This will pretty-print the JSON by indenting the output and adding new lines where appropriate. |
Set date format |
X-Sesam-Dateformat=[java date format] curl -H "X-Sesam-Dateformat:yyyy-MM-dd HH:mm:ss" http://localhost:11403/sep/api/results |
Per default, all dates will be written as long value. If you need a specific format, you can send the date format header. (see SimpleDateFormat) |
Key-Only Response |
X-Sesam-Keyonly=[comma separated list of model classes (case insensitive)] curl -H "X-Sesam-Keyonly:clients,tasks" http://localhost:11403/sep/api/results |
This will reduce found sub-objects and only transmit their primary key. Use this if data is cached to save bandwidth. |
Cyclic Calls |
X-Sesam-Cyclic=true curl -H "X-Sesam-Cyclic:true" http://localhost:11403/sep/api/server/cacheGetDiff |
Only available for specific calls. This will tell the server to not log this call in the server log files. |
Note | |
The maximum allowed size for HTTP headers is usually limited by servers rather than by HTTP spec. See also http://stackoverflow.com/questions/686217/maximum-on-http-header-values#686243. |
API calls
All available API calls are documented within the system. You can use a web browser to:
- see all existing types
- check the documentation of each method
- execute any method (by clicking the method name)
- see the result of the execution
Data types and object are described as JSON Schema.
API state
SEP API documentation shows the state of each API call. Before using a function, make sure to check its state.
Status | Description |
STABLE | Stable API call (incl. parameter), ready for production use. Documentation is verified. |
BETA | Function will stay as is, parameter and detailed functionality might change. |
DEV | Initial state. Function might be removed or renamed, functionality might change. |
DEPRECATED | Function will be removed in one of the next releases; it only exists for backwards compability. |