How to use the IXON API (APIv2)?

📘

Required module

Required module: API / Integrations. Check your modules at Admin > Licenses. To obtain this module, contact your IXON account manager or IXON distributor.

The APIv2 is the open public API of IXON. It can be used to communicate with your IXrouter, IXagent or your Historical data. The APIv2 allows you to integrate IXON's functionalities and data seamlessly with other IT systems. This way you can maximize your business value with IXON. To get you started we have explained some important basic steps and functionalities in this article.

API request architecture

👍

Development tip

A practical source of information is the IXON Cloud itself. Open your browser's network log (F12) and execute in the IXON Cloud interface what you want to do via the API. The network log will show you the exact API request, including the endpoint, headers, fields, body, and the response. You can create an overview of all API requests by selecting the type XHR and filtering on <<url>>/api. You can also use the Web Inspector to select the item that will take you to the correct API.

The APIv2 supports five types of requests: GET, POST, PATCH, PUT and DELETE. Each request consists of at least a URL and one or more headers. Additionally, fields and filters can be added to get a more organised data response. The APIv2 will respond with JSON or CSV output, depending on the endpoint.

Some API responses will not return everything you asked for in a single response and thus require you to send subsequent requests. For example, when requesting a list of your devices, you may only get up to 20 devices in the API response, while you may have more.

🚧

Use the moreAfter attribute

To make sure you get everything you're asking for, it is strongly recommended to check every API response for the moreAfter attribute. If it has the value null you received the full list in the first response. If it contains a value instead, then you'll need to send another request to get everything (details below). You may need to repeat this multiple times.

The DataList endpoint is an exception to this, because moreAfter will then always be null. For more information, see How to use historical data?.

If you need to send a subsequent request, you'll need to add a query argument to your request. You then have to insert "page-after" as the indicator and the 'moreAfter' value behind the URL of your request. Let's say for example you have 30 users in your company, and you only get 20 in your return. You can send the same request with ?page-after={20} as a query argument with the next request. You will then receive users 21-30.

Alternatively, you can request a larger response by using the page-size attribute, followed by the amount of required returns. It is still strongly recommended to check the moreAfter attribute in API responses, just in case you get back more than you anticipated. This option is limited to a maximum of 1000 returns. See the snippet below for an example of both options.

curl --request GET \
     --url "<<url>>:443/api/?page-after=$moreafter_value"

curl --request GET \
     --url "<<url>>:443/api/?page-size=$preferred_return_size"

expiresIn can be added to set the expiration date for an Authorization token. More information on this can be found in the request bearer token section of this article.

Our reference guide contains an up-to-date list of all endpoints and the headers, fields, filters, and body parameters you can add to the request. The reference guide can also give a preview of responses, and gives you the option to try a request. Samples of some common programming languages are supplied by the reference guide as well.

📘

Public ID

The APIv2 uses different ID’s for many entities. In the JSON response, there is always a row called “Type”. This will identify what kind of ID that specific public ID is. For example, the publicId in a response with type "Company" means this publicId is a "companyId

Request an Application ID

All endpoints can solely be reached when a valid Application ID is provided. Therefore, when you want to use the APIv2 you need to request an Application ID first. Please contact your Sales representative to get started with our API.

📘

Using both API1 and API2

The same Application ID can be used for API1 and API2.

Discovery: Get an up-to-date list of endpoints

The discovery serves as a starting point. Typically, a request to the discovery is made before the other endpoints are accessed: it serves as an entry point to 'discover' the other endpoints and their URLs. Endpoints will be returned as both a URL and a rel. It is recommended to use the rels in your code, and then add the most up-to-date URL from the discovery endpoint, because the URLs may be changed over time. An example of how to make a request to the discovery endpoint is given below:

curl --request GET \
     --url '<<url>>:443/api/' \
     --header 'Api-Version: 2'

Request a bearer token

Most endpoints require authentication. You can use basic authentication, which consists of your login credentials of the IXON Cloud. We advise you to switch to using a bearer token after the first request, because your requests will be processed more quickly and it's also safer than storing your password.

You can request a bearer token with the AccessTokenList endpoint. To get authorization, you need to add a header with basic authorization, which includes a cipher of your credentials. Before encrypting, this string consists of your email address and your IXON Cloud password. If you make use of Two-Factor authentication you also need to include the One Time Password (OTP) as well. The string needs to be BASE64 encoded in the request and uses the format: emailaddress:OTP:password. Without an OTP, the value to encrypt would be: emailaddress::password

Because a bearer token is temporary you also have to include ‘Expires in’ data in seconds. You can choose an expiration time between 60 seconds and 60 days (5.184.000 seconds). To make it easier to identify the bearer token you can include the field 'secretId' in the body, this is the name of the bearer token in the response. The examples below contain a request for a bearer token and the response and the required variables.

application_id='application_id'
base64_cipher_of_credentials=$(echo -n 'emailaddress::password' | base64)

curl --request POST \
     --url '<<url>>:443/api/access-tokens?fields=secretId' \
     --header 'Api-Version: 2' \
     --header  "Api-Application: $application_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Basic $base64_cipher_of_credentials" \
     --data '{"expiresIn": 3600}'

{
    "status": "success",
    "type": "AccessTokenCreateResponse",
    "data": {
        "publicId": "$response_id",
        "expiresOn": "2021-02-02T00:59:59Z",
        "secretId": "$bearer_token",
        "user": {
            "publicId": "$user_id",
            "name": "$username",
            "emailAddress": "$email_address",
            "support": false,
            "language": "en",
            "localisation": null,
            "timeZone": null,
            "registeredOn": "2020-09-01T10:59:29Z",
            "lastSeenOn": "2020-12-02T07:38:31Z",
            "termsOfUsePolicyAcceptedOn": "2020-09-01T10:59:29Z"
        }
    }
}

Identifying companies and agents (devices)

All users and agents in the IXON Cloud are part of a company. To help identify what agents and/or users you are requesting information for, many requests require a company ID. The CompanyList endpoint will return all companies that you have access to, including their public ID. Examples of the request and response, including the required headers, for a company ID are displayed below:

curl --request GET \
     --url '<<url>>:443/api/companies?fields=publicId,name' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

{
    "type": "Company",
    "data": [
        {
            "publicId": "$company_id",
            "name": "$company_name"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

Additionally, requests can require further specification for a specific agent (IXrouter or IXagent). You can request all agent ID’s in a company using the AgentList endpoint. To identify the agent we advise to include the fields PublicId, name and device ID. This way the name of the device and the MAC address/Serial Number are included as well. Examples of the request and response, including the required headers, for a company ID are displayed below:

curl --request GET \
     --url '<<url>>:443/api/agents?fields=publicId,name,deviceId' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

{
    "type": "Agent",
    "data": [
        {
            "publicId": "$agent_id",
            "name": "$agent_name",
            "deviceId": "$mac_address - $serial_number"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

Identifying data sources and tags

Once you have identified the agentId, this can be used to query for data sources and tags. This information can in turn be used to query for historical data. For more information see How to use historical data?.

Data sources

curl --request GET \
     --url "<<url>>:443/api/agents/$agent_id/data-sources?fields=publicId,name,ipAddress" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

{
    "type": "AgentDataSource",
    "data": [
      {
        "publicId": "$public_id_datasource1",
        "name": "$name_datasource1"
      }, 
      {
        "publicId": "$public_id_datasource1", 
        "name": "$name_datasource1"
      }
    ], 
    "moreAfter": null, 
    "status": "success"
}

Tags

curl --request GET \
     --url "<<url>>:443/api/agents/$agent_id/data-tags?fields=publicId,name,tagId" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

{
    "type": "AgentDataTag", 
    "data": [
      {
        "publicId": "$public_id_tag", 
        "tagId": 2, 
        "name": "$name_tag"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 4, 
        "name": "CloudLogger Error Message"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 1, 
        "name": "$name_tag"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 1, 
        "name": "$name_tag"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 3, 
        "name": "$name_tag"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 2, 
        "name": "CloudLogger Error Message"
      }
    ], 
    "moreAfter": null, 
    "status": "success"
}

📘

Note

The last query will return all data tags from all data sources that are configured on an agent.