Migration of APIv1 to APIv2

It is IXON’s mission to help industrial machine manufacturers create value with the IoT. In order to encompass more advanced features that help industrial machine manufacturers, IXON redesigned it’s API. If you want to develop with the IXON API, IXON recommends usage of the APIv2 since this is the most advanced and most frequently updated version of the IXON API. Take a look at our guide on how to use the APIv2 if you currently aren’t using the APIv1.

If you are currently using the APIv1 and want to migrate to the APIv2, don’t worry. The APIv2 looks pretty similar to the APIv1, so you will still recognise the API. Some changes have been made however. The biggest changes are discussed below. If you want to look at specific changes for certain endpoints, we recommend you to take a look at our reference guide with a up-to-date list of all APIv2 endpoints.

🚧

Migration to the IXON Cloud

To use the APIv2 you first need to migrate your company in the IXON Cloud. You can use the IXON Migration Wizard for this.

Consolidation and change of url

The APIv1 consists of 3 separate API’s, for the APIv2 the General API and the LSI have been integrated into one. This way you only have to make requests to one url for both general requests and historical data requests: https://portal.ixon.cloud:443/api/. You can now also use the same headers and authentication tokens for general API requests and historical data requests. Take a look at our guide on how to use historical and live data. IXON’s VPN Client API remains unchanged.

Discovery and headers

The APIv2 discovery is now a resource and therefore not returned as a link. The example below shows how the discovery request returns endpoints:

{
    "type": "Discovery",
    "data": [
        {
            "rel": "AccessRecoverList",
            "href": "<<url>>:443/api/access-recover"
        },
        {
            "rel": "AccessTokenList",
            "href": "<<url>>:443/api/access-tokens"
        },
            {...}
        ],
    "moreAfter": null,
    "status": "success"
}

Headers that had an IX-prefix have this prefix removed. The example below shows how some of these common headers look without this prefix:

curl --request GET \
     --url '<<url>>:443/api/' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id"

Rate limit

The APIv2 has a fair use policy when it comes to rate limiting. For standard usage, such as you might see when using our web application, you will not run into any limitations. For heavier usage, we will try to accommodate your application and return 429 responses if your application uses more than we think is fair. Therefore, we recommend that you implement a handler for a HTTP 429 too many requests response. By dynamically reducing the number of requests, after a 429, the client should be able to continue communicating with our APIs. Please contact your account manager if you encounter any limitations to your use case.

Filters

Filters were formely added as operators, they are now implemented as functions. The example below shows an applied filter in the APIv2. Please look specifically at the function structure of filters.

curl --request GET \
     --url '<<url>>:443/api/agents/{agentId}?filters=eq(publicId,"{value}")' \
     --header 'Accept: application/json' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id"

User Management

The APIv2 uses a more extensive user management system than the APIv1. Where the APIv1 uses the /categories endpoint, this has been replaced by three elements: roles, groups and access-categories. These new attributes have to be taken into account with API implementations that register users and/or IXrouter/IXagent. This also applies to API implementations that change user rights of IXrouter or IXagent groups (formerly categories).