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 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).
  • 409
    Conflict. The request could not be completed because it conflicts with the current state of the resource, for example filing a flight plan that has already been filed, or creating an aircraft type that already exists. Repeating the request unchanged will not help; the underlying state must change first.
  • 422
    Unprocessable entity. The request was well-formed but failed validation, for example a flight plan that does not pass IFPS validation or was rejected by Eurocontrol. The response body contains details on what failed.
  • 429
    Too many requests. You have exceeded a rate limit or a plan limit. Wait before retrying.
  • 500
    Internal error processing the request. This shouldn’t really happen so we’re grateful for reports and scenarios where this happens.
  • 502
    Bad gateway. An upstream system the request depends on (for example Eurocontrol/IFPS) returned an invalid or unexpected response. The request can be retried.
  • 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.
  • 504
    Gateway timeout. An upstream system the request depends on did not respond in time. The request can be retried.

In most cases you will get a more descriptive error message in the body of the response, formatted as a JSON object:

{
   "error": "human readable error message",
   "code": "STABLE_MACHINE_READABLE_CODE",
   "data": null
}

error is a human-readable message intended for display or logging. code is a stable, machine-readable identifier you can safely branch on in your application (for example DUPLICATE_FILING or FILING_VALIDATION_FAILED); it may be null for generic errors. data carries optional structured detail relevant to the error, such as a list of validation failures, and may also be null.

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. Some APIs are not documented at all and we strongly advise against inspecting the web frontend data exchange to determine the use of these undocumented APIs as we regularly perform incompatible changes to such APIs. Again, if you believe such functionality is relevant to you, contact us and ask for a stable and documented interface.

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