Servitly provides a set of REST APIs based on JSON documents exchange, that can be used to integrate your third-party software.
Endpoints
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 SSL Certificates article.
In order to make API calls, you must choose the destination environment that corresponds to a different endpoint URL.
AWS
Environment Type | Region | URL | Port |
---|---|---|---|
Sandbox | Europe (Ireland) | https://api.servitly-sandbox.com | 443 |
Production | Europe (Ireland) | https://api.servitly.com | 443 |
Production | Asia/Pacific (Hong Kong) | https://api-ap.servitly.com | 443 |
AZURE
Environment Type | Region | Certificate URL | Port |
---|---|---|---|
Develop | Europe (Frankfurt) | https://azapi.servitly-dev.com | 443 |
Staging | Europe (Frankfurt) | https://azapi.servitly-staging.com | 443 |
Production | Europe (Frankfurt) | https://azapi.servitly.com | 443 |
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 following header.
X-Semioty-Tenant: acme
Except for a few methods, before calling any API it is required to perform a login in order to obtain a JWT token that is exchanged on each subsequent API call.
The login can be done by using one of the following alternatives:
- Username and Password: this is the standard login based on the user credentials and suitable, for instance, into third-party frontend applications or Mobile applications.
- PAT: this is the login based on Personal Access Token that is recommended for cloud to cloud integration.
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 obtained JWT token has a limited duration, and when expired, it must be renewed, or a new login must be performed.
Into the body of the login response you can find:
- token: the JWT token to be sent as Bearer token
-
refreshToken: the token required to renew the JWT.
Note that the JWT can be refreshed only when expired. - userId: the ID of the authenticated user.
- tenantId: the ID of the target tenant.
{
"token": "eyJhbGciOiJIUzUxMiJ9.eyJsYX.....",
"refreshToken": "cd5352cd-b297-4149-95e5-deac47c56324",
"userId": "667ca382a6128f46aad59ee3",
"tenantId": "661233a837504726e531d68b"
}
The old cookie-based exchange mechanism has been deprecated in favor of the Bearer token exchanged through the Authorization header. The cookie-based mechanism will be gradually removed.
For more details refer to the Migrating to Authorization Header article.
Using Python
Here is reported a sample Python script that uses a PAT to login and retrieve the user identity.
Optionally you can use the login with user credentials (see commented part).
Be careful to substitute the tenant-name, use the right login PAT, API Key, and point to the desired environment.
import requests baseUrl = "https://api.servitly.com/" apiKey = "<API_KEY>" pat= "<PAT>" headers = { "X-Semioty-Tenant": "<TENANT_NAME>" } # Login with user credentials # print("==== Login with user credentials ====") # url = baseUrl + "identity/users/login?apiKey=" + apiKey # data = {"email": "<email>", "password": "*****"} # response = requests.post(url, headers=headers, json=data) # auth = response.json() # Login with PAT print("==== Login with PAT ====") url = baseUrl + "identity/users/patLogin" data = {"apiKey": apiKey, "pat": pat} response = requests.post(url, headers=headers, json=data) authResponse = response.json() # Read the JWT token print(response) print(authResponse) if "token" in authResponse: headers["Authorization"] = "Bearer " + authResponse["token"] else: quit() # Get the user identity print("\n\n==== Get user identity ====") url = baseUrl + "identity/users/me" response = requests.get(url, headers=headers) print(response.json())
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.
Be careful to substitute the tenant-name, use the right login credentials, and point to the desired environment.
Linux
curl --location --request GET "https://api.servitly.com/identity/users/me"
--header 'Authorization Bearer <JWT_TOKEN>' \
--header 'accept: application/json' \
--header 'X-Semioty-Tenant: <TENANT_NAME>'
Windows
CURL -X GET "https://api.servitly.com/identity/users/me" ^
-H "Authorization: Bearer <JWT_TOKEN>" ^
-H "accept: application/json" ^
-H "X-Semioty-Tenant: <TENANT_NAME>"
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.
Comments
0 comments
Please sign in to leave a comment.