Overview

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:

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:
 
Status Codes:

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).

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"
    }
}

Global error codes

Error code HTTP status Description
ERROR_INVALID_JSON 400 No valid JSON content provided.
ERROR_VALIDATION 400 Validation of one or more fields failed, see errors and field error codes below for details.
ERROR_AUTH 401 No or invalid token (or key) provided, see authorization.
ERROR_AUTH_EXPIRED 401 Token expired, see authorization.
ERROR_NOT_FOUND 404 Function or object does not exist.
ERROR_NOT_ALLOWED 405 Not allowed, either due to a read-only key or an expired user account.
ERROR_JSON_EXPECTED 415 Expected a request with application/json content type.

Field error codes

Error code Description
FC_MISSING_VALUE Missing value
FC_OBJ_EXPECTED The value must be an object.
FC_INT_EXPECTED The value must be an integer.
FC_P_INT_EXPECTED The value must be an integer greaten than zero.
FC_FLOAT_EXPECTED The value must be a float.
FC_BOOL_EXPECTED The value must be a boolean.
FC_STRING_EXPECTED The value must be a string.
FC_DATETIME_EXPECTED The value must be a ISO-8601 formated string (YYYY-MM-DDTHH:MM+HH:MM).
FC_DEP_MODES_EXPECTED The value must be string and W, A or S
FC_UNKNOWN_AIRPORT The given airport is unknown.
FC_UNKNOWN_AIRCRAFT The given aircraft is unkown.
FC_INVALID_ARRIVAL_TIME The arrival time must be later than the departure time.
FC_INVALID_TIME The value must be lower than the flight time.
FC_INVALID_TOTAL_TIME The manual total time exceeds the flight time.
FC_INAVLID_ECS_CYCLE The value must be lower than the total of ECS cycles.
FC_INVALID_ECS_TIME The value must be lower than total flight time.