Using SEP sesam REST API

From SEPsesam
Jump to: navigation, search

Copyright © SEP AG 1999-2017. All rights reserved.

Any form of reproduction of the contents or parts of this manual is allowed only with the express written permission from SEP AG. When compiling and designing user documentation SEP AG uses great diligence and attempts to deliver accurate and correct information. However, SEP AG cannot issue a guarantee for the contents of this manual.

Docs latest icon.png Welcome to the latest SEP sesam documentation version 4.4.3 Tigon. For previous documentation version(s), check documentation archive.


Overview

SEP sesam 4.4.3 Tigon is shipped with a REST API, which is used for the 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 Authentication.

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

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:

  1. A username and password are passed as a string, separated by colon: username:password
  2. The resulting string is encoded using the RFC2045-MIME variant of 'Base64' (not limited to 76 char/line).
  3. 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.

Information sign.png Note
  • You should not use HTTP basic authentication in a production environment. To make sure that your credentials are sent securely, use HTTPS instead of a HTTP connection.
  • Basic authentication is not recommended if you are making multiple API calls in a row; in such case, use session-based authentication.

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 reuest 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.
Information sign.png 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.

SEP API documentation.png

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.

See also

AuthenticationIntroducing JSON