Matching results

Web Services API

API Overview

This section describes the API of AirVantage. To test AirVantage API, you can view the Getting Started.

The main entity of AirVantage is a System. It represents a real system: the physical objects, the associated data and its possible interactions.
You can start to play with the API of this entity to understand how the API works.

All API access is over HTTPS and accessed from the na.airvantage.net or eu.airvantage.net URL (depending on the datacenter you use). All data is sent and received as JSON.

HTTP Verbs

Where possible, API strives to use appropriate HTTP verbs for each action.

GET
Used for retrieving resources.
POST
Used for creating resources, or performing custom actions.
PUT
Used for updating resources or collections.
DELETE
Used for deleting resources.

Authentication

AirVantage uses OAuth 2.0 to provide authorized access to its API. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a user by orchestrating an approval interaction between the user and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

The post Oauth2 Simplified explains very well the main concepts of this framework.

When a user grants access to an API Client, an Access Token is issued to access user's data using AirVantage APIs. This token has a limited lifetime of 24 hours.

There are different ways to request an access token:

To request access, an API Client MUST be registered in AirVantage.

Request an Access Token using the Authorization Code Flow

In this flow, the client application needs to obtain an authorization code before requesting and access token.
Instead of requesting authorization using the end-user credentials, the client redirects the user to AirVantage, which in turn directs the user back to the client with the authorization code.

Before directing the user back to the client with the authorization code, AirVantage authenticates the user and obtains authorization.

1. Request an authorization code

/api/oauth/authorize

Request 

GET https://na.airvantage.net/api/oauth/authorize?client_id=085d82466f824079a829f301b8a1f492&response_type=code&redirect_uri=http://www.example.org

Response

AirVantage authenticates the user and ask for authorization.
When the client application obtains authorization from the user, it is redirected to the provided redirect URI with the authorization code. 

http://www.example.org?code=1JV6zV
Name Description Use Default Type
response_type Value MUST be set to "code" required string
client_id The client id required   string
redirect_uri Not needed when a URI was previously established during the client registration process. When specified, the URI MUST be an absolute URI and MUST NOT include a fragment component. optional   string
state RECOMMENDED. This value is used by the client to maintain state between the request and callback. optional   string

2. Request token

Once the authorization code in hand, it is possible to request an access token.

The client MUST use the HTTP POST method when making access token requests. Parameters are sent in the entity-body as Form-Encoded Body Parameters. The HTTP request entity-header includes the header 

Content-Type : application/x-www-form-urlencoded


Also, the client MUST send its API client credentials when making requests to the token endpoint.

/api/oauth/token

Request 

POST https://na.airvantage.net/api/oauth/token
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=1JV6zV

Response

If your application is successfully authenticated, the authorization server will return the access token:

{

"access_token": "fe47d528-7414-4962-a7e6-ee6b82491f7a",
"refresh_token": "9b465388-c9e2-45d3-98d0-1a44a503ec40",
"token_type": "Bearer",
"expires_in": 43199,
}

In addition to the access token, the response contains the number of seconds before the token expires and a refresh token, which can be used to obtain new access tokens using the same authorization grant.

Name Description Use Default Type
grant_type Value MUST be set to "authorization_code" required string
code The authorization code requested before required   string
redirect_uri If the "redirect_uri" parameter was included in the authorization request, this field is required and their values MUST be identical. The URI MUST be an absolute URI and MUST NOT include a fragment component. required   string

Request an Access Token using the Implicit Flow

The implicit flow is a simplified authorization code flow. It is optimized for clients implemented in a browser using a scripting language. Instead of issuing an authorization code, the access token is sent directly to the redirect URI as a fragment of the request.

Before directing the user back to the client with the access token, AirVantage authenticates the user and obtains authorization.

As this flow reduces the number of round trips to obtain an access token, only one request is needed.

/api/oauth/authorize

Request 

GET https://na.airvantage.net/api/oauth/authorize?client_id=085d82466f824079a829f301b8a1f492&response_type=token&redirect_uri=http://www.exemple.org

Response

AirVantage authenticates the user and ask for authorization.
When the client application obtains authorization from the user, it is redirected to the provided callback URI with the access token in the URI fragment. 

http://www.exemple.org#access_token=1185af4a-2666-4b50-8c6e-4ee866eeaf7f&token_type=Bearer&expires_in=3600
Name Description Use Default Type
response_type Value MUST be set to "token" required string
client_id The client id required   string
redirect_uri Not needed when a URI was previously established during the client registration process. When specified, the URI MUST be an absolute URI and MUST NOT include a fragment component. optional   string
state RECOMMENDED. This value is used by the client to maintain state between the request and callback. optional   string

Request an Access Token using the Resource Owner Flow

In this flow the end-user credentials (i.e. username and password) are used directly as an authorization grant to obtain an access token.

The client MUST use the HTTP POST method when making access token requests. Parameters are sent in the entity-body as Form-Encoded Body Parameters. The HTTP request entity-header includes the header 

Content-Type : application/x-www-form-urlencoded


Also, the client MUST send its API client credentials when making requests to the token endpoint.

Request 

POST https://na.airvantage.net/api/oauth/token
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=myLogin@anymail.com&password=654dzzMk

Response

An access token is returned by the authorization server when your application is successfully authenticated:

{

"access_token": "fe47d528-7414-4962-a7e6-ee6b82491f7a",
"token_type": "Bearer"
"refresh_token": "9b465388-c9e2-45d3-98d0-1a44a503ec40",
"expires_in": 43199,
}

In addition to the access token, the response contains the number of seconds before the token expires and a refresh token, which can be used to obtain new access tokens using the same authorization grant.

Bad credentials from the end-user to a bad request - Invalid Grant. Bad credentials from an API client lead to bad request - Invalid Client.

Name Description Use Default Type
grant_type Value MUST be set to "password" required string
username The user's email, encoded as UTF-8 required   string
password The password, encoded as UTF-8 required string
factor A 6 character code sent to you via SMS when 2-factor authentication has been activated for your company. Not needed in other cases.   string

Refresh Access Tokens

Refresh tokens are typically long-lasting credentials used to obtain new access tokens when they become invalid or expired.
The client has to make a refresh request to the token endpoint by adding the right parameters.

The client MUST use the HTTP POST method when making access token requests. Parameters are sent in the entity-body as Form-Encoded Body Parameters. The HTTP request entity-header includes the header 

Content-Type : application/x-www-form-urlencoded


Also, the client MUST send its API client credentials when making requests to the token endpoint.

/api/oauth/token

Request 

POST https://na.airvantage.net/api/oauth/token
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=9b465388-c9e2-45d3-98d0-1a44a503ec40

Response

If your application is successfully authenticated, the authorization server will return a new access token along with a new refresh token:

{

"access_token": "fe47d528-7414-4962-a7e6-ee6b82491f7a",
"refresh_token": "4dae4ee7-3fce-47de-825b-bb675b60c374",
"token_type": "Bearer",
"expires_in": 43199,
}

In addition to the access token, the response contains the number of seconds before the token expires and a refresh token, which can be used to obtain new access tokens using the same authorization grant.

The refresh token is regenerated on every refresh request.
An invalid refresh token will finish with a 400 Bad Request when invalid grant.

Name Description Use Default Type
grant_type Value MUST be set to "refresh_token" required string
refresh_token The refresh token sent by the authorization server when it authenticates the client and validates the authorization grant required   string

Access Token Usage

The client accesses protected resources in AirVantage by presenting the access token

The method in which the client utilizes the access token to authenticate with the AirVantage involves using the HTTP "Authorization" request header field RFC2617

For example:

GET https://na.airvantage.net/api/v1/applications

Authorization: Bearer fe47d528-7414-4962-a7e6-ee6b82491f7

Another possibility is to send the access token in the HTTP request URI, the client adds the access token to the request URI query component. However, its use is not recommended, due to its security deficiencies.

For example:

https://na.airvantage.net/api/v1/applications?access_token=fe47d528-7414-4962-a7e6-ee6b82491f7&name=myApplication

Because of the security weaknesses associated with the URI method, including the high likelihood that the URL containing the access token will be logged, it SHOULD NOT be used unless it is impossible to transport the access token in the "Authorization" request header field.

Authenticating an API client

API Clients MUST authenticate with AirVantage when making requests to the token endpoint. Client credentials (client_id/client_secret) are issued when the API Client is registered in AirVantage.

It is highly recommended to use the HTTP Basic authentication scheme [RFC2617] to authenticate API clients with AirVantage.

For example. The user agent wishes to send the client_id "my_client" and the client_secret "the_secret". First, it will create the credentials by separating the client_id and client_secret by a single colon (:) 

my_client:the_secret
The resulting string has to be Base64 encoded (mostly all programming languages have libraries to do that. Or use an online encoder for testing). 
bXlfY2xpZW50OnRoZV9zZWNyZXQ=
The basic credentials are built like this 
Basic bXlfY2xpZW50OnRoZV9zZWNyZXQ=
Finally, the basic credentials are set into the Authorization HTTP header. 
POST https://na.airvantage.net/api/oauth/token

Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXlfY2xpZW50OnRoZV9zZWNyZXQ=

grant_type=authorization_code&code=1JV6zV&


Alternatively, the authorization server MAY support including the client credentials in the request-body using the following parameters:

Name Description Use Default Type
client_id The client id required   string
client_secret The client secret key required   string

Including the client credentials in the request-body using the two parameters is NOT RECOMMENDED and SHOULD be limited to clients unable to directly utilize the HTTP Basic authentication scheme. The parameters can only be transmitted in the request-body and MUST NOT be included in the request URI. 

POST https://na.airvantage.net/api/oauth/token

Content-Type: application/x-www-form-urlencoded

grant*type=authorization_code&code=1JV6zV&client_id=my_client*&client_secret=the_secret

Expire a Token

/api/oauth/expire

When AirVantage authenticates a client, an access token is sent with an expiration date. After this date, the token will not be valid at all.
It is also possible to expire a token explicitly. When the access_token is expired by this API, the related refresh_token will be expired too.

Request 

GET https://na.airvantage.net/api/oauth/expire?access_token=444a378a-19fe-4de9-b056-c662f633d73d

...

Response
200 OK

No specific return is sent. Only a 200 http status response is sent back.
A 401 is sent when the token is not valid.

Name Description Use Type
access_token The token to expire required string
HTTP Method GET
Requires Authentication Yes
Rate Limited No
Headers None
Permissions None

Error codes

While invoking services, several validations are made before returning results.
When errors are raised, an error code is returned with parameters. 

{

"error" : "unknown.label", // error code
"errorParameters" : "Crashed" // details relative to error code
}

Each resource service has its own error codes. However there are some generic errors.

Error Has parameters Raised when
access.forbidden No the user does not have enough rights
unknown.partner No the context is not valid for the user

Types

Name Description Example
uid Unique identifier. It is a string 16345d77a03f4882a97f79fe33cd581f
string list A comma separated string list. string1,string2,string3
string map A comma separated string map. key1:value1,key2:value2,key3:value3
timestamp number of milliseconds since January 1, 1970, 00:00:00 GMT. 1349906528204 is 10 Oct 2012 22:02:08.204 UTC
Test it here NB. Remove the last three digits in any unix timestamp convertor.

Useful Information for List

If you want to use "," character in list, you must escape it with "\".
For example:

If you want to send the following list: 
"strin,g1", "string2", "string3"
You need to write this: 
strin\,g1,string2,string3

Useful Information for Map

If you want to use "," or ":" characters in map, you must escape them with "\".
For example:

If you want to make the following map: 
"key1":"val:ue1", "key2":"valu,e2", "key3":"val,:ue3"
You need to write this: 
key1:val\:ue1,key2:valu\,e2,key3:val\,\:ue3

Paging

All queries returning a list of resources are paginated. Default pagination does not have any offset and may contain up to 100 elements.

Use the following Request Parameters to paginate your queries

  • offset: Set the first row to retrieve. If not set, rows will be retrieved from the beginning.
  • size: Set the maximum number of items to retrieve (between 0 and 500). If not set, a maximum of 100 items will be returned.

Example:

https://na.airvantage.net/api/v1/applications will return a maximum of 100 applications from the first record.

https://na.airvantage.net/api/v1/applications?offset=50 will return a maximum of 100 applications beginning from the 50th record.

https://na.airvantage.net/api/v1/applications?size=50 will return a maximum of 50 applications from the first record.

https://na.airvantage.net/api/v1/applications?offset=50&size=50 will return a maximum of 50 applications beginning from the 50th record.

The returned list will have

  • items : an array with at must size items that matched the criteria (with the value of size from the query)
  • size : the number of elements returned (should be the same as items.length)
  • count : the total number of elements that matched the criteria in the database (potentially much more than the value of size from the query)

Example :

Assuming there are 100 applications in the DB, and 50 applications that match the criteria,

https://na.airvantage.net/api/v1/applications?size=3&criteria=whatever would return 

{

items : [ { uid : "..." } , { uid : "..." } , { uid : "..." } ],
size : 3,
count : 50
}

Filtering

It is also possible to ask only specific information. Instead of getting items with an unneeded record, clients can filter the fields that have to be returned.

Use the request parameter: fields, which is a string list. See types sections to see how to build string lists.

https://na.airvantage.net/api/v1/applications?fields=state,name will return applications filled up only with their unique identifier, their state and their name.

When the fields parameter is missing, only default attributes are returned. Default attributes are dependent of the returned records.

Sorting

When queries are requested, results can be sorted.

Sorting results are done using the asc and desc fields. As you may guess asc stands for ascending order and desc for descending order.

The following line will return all the applications visible to the caller. Results will be sorted from the first created to the last created.
Do not forget that results are paginated. 

https://na.airvantage.net/api/v1/applications?asc=creation

You can also sort by several fields.

https://na.airvantage.net/api/v1/applications?asc=creation,name

In previous call, result items will be sorted first by creation date, from the first created to the last, and then by name.

It is possible to combine ascending and descending sortings

https://na.airvantage.net/api/v1/applications?asc=creation&desc=name

It is important to know that ASC sortings are done first.

When an attribute is sent accidentally in either asc or desc, The asc ordering will be ignored.

https://na.airvantage.net/api/v1/applications?asc=name,creation&desc=name

The previous call will sort by creation ascending and by name descending.

See the information frame on GET methods to know which fields can be sorted.

Password rules

Rules use to validate a password are as follows:

  • Require between 8 and 16 chars
  • Require at least 1 digit
  • Require at least 1 non-alphanumeric char
  • Require at least 1 alphabetical char
  • White space are prohibited
  • Alphabetical sequences are prohibited
  • Numerical sequences are prohibited
  • Qwerty sequences are prohibited
  • 4 repeat characters are prohibited
TOP