Servitly provides a set of REST APIs based on JSON documents exchange, that can be used to integrate your third-party software.

All API endpoints are reachable only via an HTTPS connection which is secured by the Servitly SSL certificate, which is subject to expiration and renewal. For more information about how to deal with certificates, refer to the Security Overview article.

In order to make API calls, you must choose the destination environment that corresponds to a different endpoint URL, and you must provide the name of the tenant to connect to.

How to make API Requests

In addition to the target environment, the name of the application is also needed and must be sent in each request as the "X-Semioty-Tenant" header.

Except for a few methods, before calling any API it is required to perform a login by issuing a username and password in order to obtain a JWT token that is exchanged on each subsequent API call.

Moreover, to identify the client performing an API call, you need an API Key, that can be configured within the target environment, for more details refer to the API Keys article.

The login response returns a JWT token as a set cookie, and all subsequent requests must include that cookie to provide the backend with the JWT cookie.

The obtained JWT token has a limited duration, and when expired, it must be renewed, or a new login must be performed. 

Using CURL

Here is reported a sample script (Linux and Window) that uses the CURL command to perform the login, store the token in a local file and finally retrieve the user identity by performing an authenticated API call.

Linux

curl --location --request POST 'https://api.servitly.com/identity/users/login?apiKey=123abc' \
--header 'accept: *' \
--header 'Content-Type: application/json' \
--header 'X-Semioty-Tenant: <tenant-name>' \
--header 'X-Semioty-Path: Direct access' \
--data-raw '{"email":"foo.bar@acme.com","password":"*****"}' \
--cookie-jar jwt_cookie.txt https://api.servitly.com > log1.txt

curl --location --request GET "https://api.servitly.com/identity/users/me" 
--header 'accept: application/json' \
--header 'X-Semioty-Tenant: <tenant-name>' \
--header 'X-Semioty-Path: Direct access' \
-b jwt_cookie.txt > log2.txt

Windows

curl -X POST "https://api.servitly.com/identity/users/login?apiKey=123abc" ^
-H "accept: *" ^
-H "Content-Type: application/json" ^
-H "X-Semioty-Tenant: <tenant-name>" ^
-H "X-Semioty-Path: Direct access" ^
--data "{\"email\":\"foo.bar@acme.com\",\"password\":\"*****\"}" ^
-c jwt_cookie.txt https://api.servitly.com > log1.txt

CURL -X GET "https://api.servitly.com/identity/users/me" ^
-H "accept: application/json" ^
-H "X-Semioty-Tenant: <tenant-name>" ^
-H "X-Semioty-Path: Direct access" ^
-b jwt_cookie.txt > log2.txt

Be careful to substitute the tenant-name, use the right login credentials, and point to the desired environment.

Swagger

Within the REST API Reference page, you can inspect all the available endpoints and directly test the REST API. Note that, due to the presence of cookies within the browser, the login session is the same as you are navigating the application within the same browser. We suggest you use a different browser to test the API through Swagger.

Requests Rate Limits

The number of requests an API client can perform is subject to limitation depending on how the API Key is configured.

Moreover, there is a limit that is globally applied to the environment, and by default is 2000 requests/minute, if you need more, you must contact Servitly support.

When an API request is received, the backend verifies the rate limit according to the API Key used by the client, after that verifies also the overall environment limit.
If one of the rate limits is exceeded, the HTTP error code 429 is returned. 

The rate limit configured on the API Key depends also on its restrictions, in the case of None or Web Site the rate limit is computed as total among all clients using such key, instead in the case of Mobile App the rate limit is computed per device. 

Rate limits are verified through a bucket based on a one-minute sliding window. A token is consumed for each request, and the bucket ensures a certain amount of tokens per period of time.

In case of Hours or Days as for Max request time unit, the period is subdivided into slots of one minute length, each of which has a certain number of tokens depending on the rate limit. 

When the client runs out of tokens, the excess requests are refused, and to perform new requests the client has to wait one minute to get more tokens.

Example 1

Suppose a rate limit of 600 data requests/hour, this means you can perform 10 requests per minute.

When exceeded, you have to wait 1 minute to make other 10 requests.

Example 2

Suppose a rate limit of 24 * 60 data requests/day, this means you can perform 1 requests per minute.

When exceeded, you have to wait 1 minute to make another request.

Example 3

Suppose a rate limit of 100 data requests/minute, this means you can perform 100 requests per minute.

When exceeded, you have to wait 1 minute to make other 100 requests.