Basics
All endpoints are located under the th base URL https://antares.delisky.com/
RESTful API
Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint.
Where possible, DeliSky API uses appropriate HTTP verbs for each action:
| Method |
Action |
| GET |
Retrieves resources |
| POST |
Create resources |
| PUT |
Changes and/or replaces resources |
| DELETE |
Deletes resources |
Responses
All response data is returned as a JSON object.
Depending on it's type the response can contain on or more of the following properties:
{
"success": true,
"message": "string",
"data": { },
"validationErrors": [ ]
}
| Property |
Description |
| success |
Usually is true if the HTTP status code is in the 2xx range and false, if it is
400
or higher.
This means you could also check the HTTP status, it's just for convenience.
|
| message |
The message property gives more details about the returned status and data.
Usually this contains only a message, if something went wrong.
|
| data |
The data object contains the actual data. It always contains a property named after
the data type e.g. "airports" for a collection of airports or
"order" for a single order.
|
| validationErrors |
The validationErrors property is used for validation errors, where
property_name
is the name of the invalid property and the value the error message.
If there are no errors, the errors object is null.
|
Response
200 OK
{
"success": true,
"message": "string",
"data": {
"airports": [{ ... }],
"totalItems": 100,
"page": 1,
"pageSize": 20,
"totalPages": 5,
}
Some endpoints support a way of paging the dataset. If you make use of it
totalItems, page, pageSize and totalPages
are provided in addition to the returned data items.
| Property |
Description |
| totalItems |
Indicates the total number of items in the collection.
|
| page |
Indicates the current page number.
|
| pageSize |
Indicates the number of items per page.
The default value is 20 (only applied, if a page is specified as well)
|
| totalPages |
Indicates the total number of pages used for the collection.
|
Error responses contain a message that describes what went wrong.
Response
400 Bad Request
401 Unauthorized
404 Not Found
405 Method Not allowed
408 Request Timeout
{
"success": false,
"message": "Describes the error",
}
Even if your app has been authenticated successfully and the access token is sent with
the request's header, there are situations where you get a 401 Unauthorized response.
For example, if you try to access another user's order:
Response
401 Unauthorized
{
"success": false,
"message": "You are not allowed to access this resource"
}
When creating or updating a resource the input is validated. If any validation error
occurs the HTTP status is 422 Unprocessable and the response contains a
validationErrors object.
Response
422 Unprocessable
{
"success": false,
"validationErrors": {
"aircraftRegistration": [ "The aircraft registration is required" ],
"deliveryDate": [
"Plese enter a valid date",
"The delivery date must be in the future"
]
}
}
Authorization/Authentication
All requests to the DeliSky API require authentication. Your application must provide
the access token as a Bearer token in the HTTP Authorization
header.
'Authorization': 'Bearer <access_token>'
If the request doesn't contain the Authorization header or if the token is invalid or expired,
the API responds with a '401 Unauthorized' status.
Obtain a token
In order to authenticate a user and retrieve the access token send a POST request
to the /Auth/Token endpoint. The request body must contain the
username and the password of the user as well as an API key. (Don't have an API key yet? Please
contact us at info@delisky.com)
Request
POST https://antares.delisky.com/Auth/Token
{
"username": "username",
"password": "secret",
"apiKey": "A3p5i34K25E23783y"
}
On successful authentication the API returns a 200 OK response containing the authorization token.
Response
200 OK
{
"success": true,
"data": {
"token": "eyJhbG...2Jk",
"tokenType": "Bearer",
"lifetime": 600000,
"username": "username"
}
}
In addition an HttpOnly cookie with a refresh token is set.
This is used to do a silent refresh of the authentication token.
| property |
description |
| token |
This is the authorization token that must be included in the Authorization
header of each request to the API:
'Authorization': 'Bearer <authorization_token>'
|
| tokenType |
Type of the returned token. Always 'Bearer' |
| lifetime |
The authorization token's lifetime in milliseconds |
| refreshToken |
A refresh token that can be used to retrieve a new authorization token without
to login again.
|
Note:
If you'd like to manage the refresh token yourself, add the query paramater ?useCookies=true
to the request. In this case, the refresh token is included in the response body.
If the user's credentials are not valid the API responds with 400 Bad Request.
Response
400 Bad Request
{
"success": false,
"messge": "The username or password is incorrect."
}
Refresh a token
When calling the /Auth/Login endpoint two cookies are sent with the response.
One with the user name and one with a refresh token. With the help of these you can request
a refreshed access token, so the user doesn't have to provide the login credentials everytime
the access token has expired. In order to get a refreshed token your application must send the
provide the cookies along with the api key to the /Auth/Refresh endpoint:
Request
POST https://antares.delisky.com/Auth/Refresh
{
"apiKey": "A3p5i34K25E23783y"
}
If the cookies are present and the refresh token is valid, a new token is returned.
Response
200 OK
{
"success": true,
"data": {
"token": "geThnR...4Wg",
"tokenType": "Bearer",
"lifetime": 600000,
}
}
Note:
If you chose to manage the refresh token yourself (not using the cookie), you have to
set the query parameter ?useCookies=false and include the refresh token and the username in the request body
("refreshToken": "ZuqiFs...78B", "userName": "userName")
Logout
You can't really log out from the API. To log out the application, simply make sure
that the Authorization Header with the access token is not sent.
To make sure the refresh token can't be used to get a new token, it can be invalidated
using the /Auth/Logout endpoint. Setting logoutFromAllDevices
to true invalidates all refresh tokens on the server, so no client can request
a refreshed token.
Request
POST https://antares.delisky.com/Auth/Logout
{
"username": "username",
"refreshToken": "ZuqiFs...78B",
"logoutFromAllDevices": true
}
Versioning
The DeliSky API follows Semantic Versioning principles,
though only with MAJOR and MINOR version. This means that with a version number x.y:
-
When releasing breaking changes, we make a major release
by changing the x number (e.g. 3.4 to 4.0)
-
When releasing new features or bug fixes that introduce no
breaking changes, we make a
minor release by changing the y number (e.g. 3.4 to 3.5)
We do not consider breaking changes:
- Addition of new properties in response data
- Not returning a property instead of returning it with a value of
null (or vice
versa)
- Changing the order of the properties in the response body
Choosing an API version
There are two ways to explicitly specify the API version, you want to use:
Either specify the version by adding an 'X-Api-Version' header
to the request:
'X-Api-Version': '3.0'
or put the version number in the query string:
https://antares.delisky.com/Airports/?version=3.0
Default API version
If no version is specified, we assume, you want to use the latest stable version
of the API.
Supported versions
Each response contains a header with supported and an other with deprecated API version numbers:
'api-supported-versions': '3.0, 3.1'
'api-deprecated-versions': '2.8, 2.9'