Application Programming Interface

Introduction

The autorouter web interface is built on top of a RESTful API exporting the complete autorouter functionality. This application programming interface (API) is also available to 3rd party applications.

Clients issue HTTPS requests to the autorouter server, making use of the HTTP request types GET, POST, PUT and DELETE with request specific URLs and passing input data as either HTTP parameters or JSON formatted messages in the request body. Responses can be HTTP status codes or JSON messages in the body.

Structure

The API is structured around the following principal entities:

Typically, operations are performed on these entities where GET retrieves information, POST creates an entity or performs an operation, PUT updates/replaces an entity and DELETE removes an entity.

Authentication

The web frontend to autorouter contains an email / password authentication (alternatively an external OAuth 2.0 authentication from 3rd party ID providers) and uses session cookies to authenticate individual API calls during the lifetime of the session. This is typically not practical for API users which is why an additional method is offered.

You will find more information on how to perform the authentication here: Authentication via OAuth 2.0

API invocation

The RESTful API is located at

https://api.autorouter.aero/v1.0/<group>/<request>

for example a HTTP POST to

https://api.autorouter.aero/v1.0/router

to create a new route.

API requests return a HTTP status code. The following status codes are used:

  • 200
    Request completed successfully.
  • 400
    Invalid request data. Some of the data passed to the call is not valid.
  • 401
    Not authorized. You did either supplier no credentials, expired credentials or invalid credentials. You can try the request again with correct credentials.
  • 403
    Access denied. You do not have permission to access the resource or perform the operation. Repeating the request will not help.
  • 404
    Object not found. Most likely an object referenced through the request URL was not found or could not be accessed due to insufficient privileges (the API will not tell you that for security reasons).
  • 500
    Internal error processing the request. This shouldn’t really happen so we’re grateful for reports and scenarios where this happens.
  • 503
    The server cannot handle the request at the given time due to capacity issues. The request should be attempted again at a later time. If the issue is frequent or prevails over a longer period of time, a support ticket should be opened.

In most cases you will get a more descriptive error message in the body of the response.

Versioning

The API is guaranteed to remain interface compatible in line with the Semantic Versioning specification in which a version is comprised of 3 numbers in the format MAJOR.MINOR.PATCH where an increment of each component has the following meaning:

  • MAJOR
    When incompatible API changes are made.
  • MINOR
    When functionality is added in a backwards-compatible manner.
  • PATCH
    When backwards-compatible bug fixes are applied.

Some APIs are documented as “unstable“. For these APIs, the above interface stability guarantee does not apply. They may see incompatible changes between minor version updates. If you rely on an unstable API, please contact us to discuss your needs and how we can promote it to stable API.

To query the current version of the API, perform the following request

HTTP GET https://api.autorouter.aero/v1.0/system/version

This returns a JSON structure containing the major and minor version number.

{
   "major": 1,
   "minor": 0,
   "patch": 19,
   /* whether this is a production system (false for test/sandbox system) */
   "production": true,
   /* the minimum version of the API supported by the server */
   "minVersion":
   {
      "major": 1,
      "minor": 0
   },
   /* whether the system considers the call to be authenticated */
   "auth": false
}

All invocations of the API contain the major and minor number as part of the URL (https://api.autorouter.aero/v1.0). This allows the platform to introduce changes to the API but maintain backwards compatibility by continuing to provide the previous version of the API which requires knowing which version of the API the client expects. If you omit the version number, the server will assume the latest version of the API. It is beneficial to check back regularly for the latest API revision and adapt your application to make use of it. This will both give you access to added capabilities and keep you close to development so that when a major update happens and a previous version is finally retired from service, you most likely won’t have to make any changes or only small changes to your application. The API changes for each version number are documented in the API changelog.

Messages

Certain events trigger messages that clients can subscribe to using the message queue facility.

Samples