Getting Started with the AirVantage API

Integrate and extend your AirVantage platform

Here we give you an overview of what you can do with the AirVantage API via a simple use case: getting raw data from your system, then using a chart to display it in an application.

We’ll explain all the technical aspects needed:

basic API syntax,

authentication,

AirVantage integration,

how to do simple GET calls.

1 / Basics

2 / Authenticate

3 / Develop

4 / Test

Basics

What can you do with the API?

The AirVantage API provides a powerful and flexible interface between deployed devices and AirVantage. You can use it to develop custom applications for your business needs, whatever the domain: smart Phone, CRM, ERP…

For example, you can use the API to:

Exploit raw applicative data and aggregated fleet data.
Create script-based Firmware Upgrade campaigns
Remotely monitor and manage devices to avoid field intervention.

Which tool can you use?

Start by installing a REST Client like:

Postman can be used to test your API calls with AirVantage
cURL can be used as well as command line tools to transfer data (not described in this tutorial).

Or use a browser-specific client:

Chrome: Postman
Firefox: RESTClient

For more details, see the API documentation .

What are REST APIs?

This is the typical format of our REST API

Request:

GET https://{server}/api/v1/users/current

Authorization: Bearer {token}

HTTP verb	Base URI	Resource Path	Parameters
GET	https://{server}/api/v1	/users/current	?param={value}

Response:

{
  uid: "81210eca05484d34a29bc6c34dc31bf7",
  email: "dsciamma@sierrawireless.com",
  name: "David Sciamma",
  company: {
    uid: "97ba9e22078548a2847912a87152e3f4",
    name: "Sierra Wireless"
  },
  profile: {
    uid: "df1c0f7d5f8c4db2b45978f98e1093ad",
    name: "Manager"
  }
}

REST (Representational state transfer)

HTTP based RESTful APIs are defined with these aspects:

Base URI, such as http://example.com/resources/
An Internet media type (JSON, XML, RSS, CSV …) must be defined. Most of the time, application/json is used.
Standard HTTP methods:
- GET - Used for retrieving resources,
- POST - Used for creating resources, performing custom actions,
- PUT - Used for updating resources or collections.
- DELETE - Used for deleting resources
Hypertext links

(src: Wikipedia )

JSON (JavaScript Object Notation)

JSON stands for JavaScript Object Notation, is an open standard format that uses human-readable text to transmit data objects consisting of attribute-value pairs. It is used primarily to transmit data between a server and web application, as an alternative to XML. (src: Wikipedia )

Widely adopted
Language independent
Simple (set of attribute-value pairs)
Types
Number, String, Boolean, Array, Object, null

Use API with authentication

To integrate to AirVantage APIs, you will first need to authenticate. This requires:

An API Client identifier
Support for one of the OAuth Flow methods described below

Implement authentication

AirVantage uses the OAuth 2.0 protocol for authentication. AirVantage supports three ways of getting an access token. Select the flow that best suits your application:

The Authorization Code Flow: This should be the preferred flow for server-side applications. This flow is great if your code can keep a secret. The application will get an access token and a refresh token. The refresh token can then be stored by the application and used later to get a new access token without asking the user again for credentials. For native applications such as mobile apps or applications who cannot keep secrets you MUST use the PCKE (RFC 7636) extension to the Authorization Code flow to prevent CSRF and authorization code injection attacks. PKCE is not a replacement for a client secret, and PKCE is recommended even if a client is using a client secret.
The Resource Owner Flow: This flow can be used if the user trusts the application e.g. you’re a company and you’re developing an application only used by your employees then they don’t need to give their credentials to the application.

You can find more details about how authentication works as well as sample API calls in this AirVantage API documentation section .

Note: Postman supports the Authorization code!

Specs: rfc6749

Create an API Client

The first step in order to use AirVantage API is to create an API Client. The API Client represents the identity of the application that needs to connect to AirVantage API. All the API calls will be traced and related to an API Client. An API Client consists in:

Go to Develop > API Clients
Click on the Create action
In the Create API Client modal:
Provide a Name
A Logo URL: (optional) You can set a URL for the logo of your application. This logo will be display in the OAuth authorization dialog
A Client ID and a Secret Key: Both are generated by AirVantage
A Redirect URL (Recommended): OAuth will use this URL during the Authorization code and the Implicit flow to redirect the user after the authorization dialog. It is strongly recommended to set one for native applications.

To create an API Client, go to AirVantage > Develop > API Clients: https://eu.airvantage.net/develop/api/clients . The following chapter of the User Guide explains the steps to create an API Client .

Get an Access Token

The method depends on which Oauth flow method your application uses. Here are two examples:

Get an access token using Resource owner flow

Token url: https://eu.airvantage.net/api/oauth/token
Use provided API clients credentials (client_id and client_secret) and your user credentials (username and password)
HTTP Method: POST
Header: content-type: application/x-www-form-urlencoded

Here’s the full URL to complete:

https://eu.airvantage.net/api/oauth/token

Content-Type: application/x-www-form-urlencoded
grant_type=password&username={username}&password={password}&client_id={client_id}&client_secret={client_secret}

This is how it looks in Postman:

OR Get an access token using Authorization Code flow

Authorize url: https://eu.airvantage.net/api/oauth/authorize
Token url: https://eu.airvantage.net/api/oauth/token
- Client-id: 46147801a4af4432a5a45dfb68db927a
- Client secret: 6fff692d93494e39ba511d5a099ba352
Save the token: demoToken

Tokens are your own property and responsibility: Never share a token with anyone or between two applications. For example, don’t share it in a public source repository.

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, replace {accessToken} by your access token in the Authorization header:

GET https://na.airvantage.net/api/v1/applications 
Authorization: Bearer {accessToken}

Why you must not use a token as a parameter...

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://eu.airvantage.net/api/v1/applications?access_token={accessToken}&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.

Develop an application

Once you have created the API Client and picked the most appropriate OAuth2 flow for your application, you can start calling the AirVantage API using the language of your choice (Java, Javascript, Ruby, Python…).

AirVantage provides all the features in its API, making it really easy to integrate with your backend to automate your flows.

Have a look at the API & Examples page to find API Libraries in several languages to illustrate what will be described below.

Getting your system

First, you need to get your system information. One of the most important field is the uid which is used by the API to identify your system.

Get information about your systems, using the API:

> GET https://{server}/api/v1/systems?name=MySystem&fields=uid,name,gateway,subscriptions

Authorization: Bearer {token}

Copy the uid field from the response below:

{
   "items":    [
            {
         "uid": "3ed6cd7426604ee0bca9fe01f2521230",
         "name": "MySystem",
         "gateway":          {
            "uid": "12e4b922b0034b26a92e7f9934da13ae",
            "imei": null,
            "macAddress": null,
            "serialNumber": "458555527",
            "type": null,
            "creationDate": "1337948436603"
         },
         "subscriptions" : [{
            "uid": "bafd571985d641d7b159dc7ef3214f5d",
            "identifier" : "4569874563254156984",
            "mobileNumber": null,
            "networkIdentifier": null,
            "operator": "UNKNOWN",
            "state" : "INVENTORY"
         }]
      }
      ]
}

GETting the raw Data

Once you can identify your system, you are ready to get data values from it.

To list the historical values for a given data type from a system:

> GET https://{server}/api/v1/systems/data/raw?
      targetIds={system_uid}&dataIds={data_id}

Authorization: Bearer {token}

For example: data_id can be phone.custom1

{
    "e1fb7e79d96142b699025c47e80db642": {
        "phone.custom1": [
            {
                "ts": 1423505823059,
                "v": 3543
            },
            {
                "ts": 1423505703042,
                "v": 3519
            },
            {
                "ts": 1423505583042,
                "v": 3495
            },
            {
                "ts": 1423505463035,
                "v": 3472
            },
            {
                "ts": 1423505343056,
                "v": 3448
            },
            {
                "ts": 1423505223034,
                "v": 3424
            },
            {
                "ts": 1423505102624,
                "v": 3401
            }
        ]
    }
}

POSTing a command

Now, an applicative command will be sent to the system using the Systems > Applicative command API.

Note this API is a POST HTTP Request. So you have to define a body to supply information (about your command).

This API doesn’t need any parameter. All information are in the body:

Define HTTP Method: POST
Define content-type header: application/json and Authorization
Select JSON (application/json) for the body format
Fill the body with the information: system uuid, command path get from the application detail (like data path in the previous step), define parameters.

> POST https://eu.airvantage.net/api/v1/operations/systems/command

Authorization: Bearer {token}

Body:

{ "systems" : { 
     "uids": "f3b85a32195644bbafe836fee64ec260" }, 
  "commandId": "container.doorLED",
  "parameters": { 
     "status": "true"
 }
}

Response:

 HTTP/1.1 200 OK
 Content-Type: application/json

{ "operation":"4b89657f63aac4b299c1d46e98a495326" }

You can send a command which is not described in the application model.

In this case, note the devices can be contacted using various channels. For example, AirVantage can send a command through the device management channel based on the protocol lightweightM2M or OMA DM or through the application channel like MQTT or CoAP. In most of the cases, 2 protocols can be used to communicate with the device, as a result, you must define the protocol to be used. If not, an error Command protocol cannot be found for the system is raised and the command is never sent. If a single protocol is defined, the command is sent using this protocol.

Keep this operation uuid for the next API call.

Getting more information about an operation

This API uses the previous result to find more information about the operation we have just created:

Get the operation uuid. We reference it as {operation} in the example below.
Define HTTP Method: GET (default)
Define content-type header: application/json and Authorization
Fill the URL field with the operation uuid

GET https://eu.airvantage.net/api/v1/operations/{operation}

Authorization: Bearer {token}

Have a look on the API & Examples page to find API Libraries in several languages to illustrate what you saw here.

Tools to tinker with the APIs

You can use AirVantage to see how the user interface call the API as examples. You needs Google Chrome developer tools (also exists in Firefox or Internet Explorer):

Log into AirVantage and open the dev tools panel by pressing F12.
Select the Network tab, then click the XHR filter.
You can now watch API requests in real time! Click the AirVantage UI to see the underlying request.

Test your application

OK! So now you have a running application, don’t forget to deploy it on a web server that can be accessed by AirVantage. For better integration with AirVantage, HTTPS access to your application is recommended.

All set!

Now that you can get data from AirVantage, you can create charts, tables, show alerts in your custom application using the API. For more details, see AirVantage API Reference

Now you’re ready to go further and develop features such as:

Web applications to display your business data
Mobile applications to control your devices from your smartphone
Your own business dashboards using existing tools
Integration in your IT
Integrations with other online services like Salesforce, Zoho, Zapier, etc

More resources

Also take a look at the API Libraries & Examples to find more sample applications!

Have a look to how to upgrade systems with API

Matching results