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.