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.
Error Handling
API requests return a HTTP status code and optionally an error structure with more information. See the dedicated section for a summary of all possible error conditions.
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.