The FsHub REST API (V3) is performance optimised and adds new functionality over the older V2 API, the REST API enables you to access profile, airport, airline, landing and flight data in a simple, programmatic way using conventional HTTP requests.
All of the functionality that you are familiar with on the FsHub website is also available through the API, allowing you to script and retrieve data for applications, IoT projects, mobile apps or websites.
The API documentation will start with a general overview about the design and technology that has been implemented, followed by reference information about specific endpoints.
Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests should be made using the HTTPS protocol so that traffic is encrypted.
For simple retrieval of information about your account, flights, aerodrome data and METAR reports, you should use the HTTP GET method. The information you request will be returned to you as a JSON object.
The attributes defined by the JSON object can be used to form additional requests. Any request using the GET method is read-only and will not affect any of the objects you are querying.
Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.
In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.
In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.
Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.
If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.
When a request is successful, a response body will typically be sent back in the form of a JSON object.
The value of these keys will generally be a JSON object for a request on a single object and an array of objects for a request on a collection of objects.
In addition to the main resource root, the response may also contain a meta object. This object contains information about the response itself.
The meta object contains a total key that is set to the total number of objects returned by the request. This has implications on the links object and pagination.
The meta object will only be displayed when it has a value. Currently, the meta object will have a value when a request is made on a collection (like droplets or domains).
To access the V3 API, you must specifiy a Personal Access Token.
When making API requests, you should specify the token as a HTTP header, the HTTP header name should be X-Pilot-Token, the value should be the token string.
When attempting to access the API without a valid token, the following response object will be received:
{
"error": {
"status_code": 401,
"message": "Valid token was not provided."
}
}
Our latest (v3) API enables users, to instead having to specify the X-Pilot-Token as a HTTP request header, this can also now be set as a URL parameter like so: ?X-Pilot-Token={TOKEN_HERE}. The preferred option however is to set it as a HTTP Header.
When an error is returned from the API, instead of having a "data" root, an "error" root will instead be returned with details of the error, the following response object, an example of the format will be received:
{
"error": true,
"message": "Airport not found.",
"details": {
"icao": "AAAA"
}
}
Endpoints that respond with collections of data utilise some additional URL parameters for limiting results and moving through data-sets.
The limit parameter enables you to reduce or increase the number of collection items returned, the cursor parameter enables to you offset your results returned.
If no limit or cursor parameters are present in the request, the number of collection items are automatically set to 10 and the cursor at the beginning of the data set.
You can see all available v3 endpoints at the Swagger UI page
The Swagger UI is coming soon. Please refer to the old developer documentation for API endpoints: https://fshub.io/docs/platform/v3/rest-api