Accessing the API¶

All API functions can be accessed with HTTP request. The base URL is https://mycontrol.aero/api/:version (HTTPS only!), where version is either latest or any older supported version.

The get the currently available versions make a GET request to api.

GET api¶

Example request

GET /api HTTP/1.1

curl -i https://mycontrol.aero/api

Example response

HTTP/1.0 200 OK
Content-Type: application/json; charset=UTF-8

{
    "versions": {
        "1.0": "1.0",
        "latest": "latest"
    }
}

Status Codes:

• 200 OK – No error

All API functions use Content-Type: application/json for requests and responses.

Authorization¶

To access data of a user through the API, you need an access key generated by the user (under “Profile” / “Apps”). Once you have a key, you can request a token, which is used for all other request.

A token will be valid for one hour, afterwards you have to request a new one.

To request a token, make a GET to token and provide the API key via HTTP basic authentication in the username part (the password part is not used).

GET api/latest/token¶

Example request

GET /api/latest/token HTTP/1.1
Authorization: Basic NTUyMjk4ZjctY...

curl -i \
     -u 49592602-3cc3-4fb7-9fbe-e1f016f553af: \
     https://mycontrol.aero/api/latest/token

Example response

HTTP/1.0 200 OK
Content-Type: application/json; charset=UTF-8

{
    "token": "eyJhbGciOiJIUzI1NiIs..."
}

Request Headers:

• Authorization – API key

Status Codes:

• 200 OK – No error

• 401 Unauthorized – Invalid API key

The access token must be provided with all requests using the the username part of the HTTP basic authentication (the password part is not used).

Pagination¶

Some requests will be paginated to a limited number of items. The pagination information is included in the Link header. You can follow these links or specify the page directly with the page query parameter. The links are also included in the request body for convenience.

Example request:

GET /api/latest/flights?page=10 HTTP/1.1
Authorization: Basic NTUyMjk4ZjctY...

curl -i \
     -u eyJhbGciOiJIUzI1NiIsImV4cCI6MTQwMjk5MTA2MCwiaWF0IjoxNDAyOTg3NDYwfQ.eyJpZCI6Ijg3YTBlZmViLTEzNjgtNGU4Mi1hYzVkLTZiYWQ0YzYzZGZiYiJ9.c9kn43-6DtQp2qHFaHpztxe6cEWwXDbBOmF4T9yQ_n4: \
     https://mycontrol.aero/api/latest/flights?page=10

Example response:

HTTP/1.0 200 OK
Link: <http://mycontrol.aero/api/latest/flights?page=11>; rel="next",
      <http://mycontrol.aero/api/latest/flights?page=9>; rel="prev",
      <http://mycontrol.aero/api/latest/flights?page=1>; rel="first",
      <http://mycontrol.aero/api/latest/flights?page=21>; rel="last"
Content-Type: application/json; charset=UTF-8

{
    "flights": [
        {"id": "79f63228-d148-4fab-b3f3-bfbaf5dfb728"},
        {"id": "c56e359c-3898-41c3-8661-8ff738a405ab"},
        {"id": "b8c06d8a-bccb-4e2a-bce6-b4d278b30bb0"},
        {"id": "10fb7295-12ba-43c6-8603-c7166bdd0210"},
        {"id": "300e9c64-2059-4fa2-9790-3d542fe7ac87"},
        {"id": "264cb442-4be6-45f5-ba20-45630aefc146"},
        {"id": "61d1b506-e402-4d14-a1d9-682c2c20ed2a"},
        {"id": "eabf3f66-1e9c-4aa5-bbb4-cf7d7e615f20"},
        {"id": "a9ac5c8e-9de6-4242-9525-04faf948e64d"},
        {"id": "fe2fc533-05be-4df5-9697-a8a8a48b4eb6"}
    ],
    "links": {
        "next": {"href": "http://mycontrol.aero/api/latest/flights?page=11"},
        "prev": {"href": "http://mycontrol.aero/api/latest/flights?page=9"},
        "first": {"href": "http://mycontrol.aero/api/latest/flights?page=1"},
        "last": {"href": "http://mycontrol.aero/api/latest/flights?page=21"}
    }
}

The possible rel values are:

Error responses¶

If a request results with an error, the JSON body of the response contains additional information. There is one global code and message and one for each field (parameters).

HTTP/1.0 400 Bad Request
Content-Type: application/json; charset=UTF-8

{
    "message": "Validation failed",
    "code": "ERROR_VALIDATION",
    "errors": {
        "field": "departures/hdf",
        "message": "Integer expected",
        "code": "FC_INT_EXPECTED"
    }
}