The FsHub REST API (V3) 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. If you keep having issues with a specific endpoint, please Contact Us with details of the endpoint and payload you are providing.
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 object, 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 for any request.
If you do not have a PAT yet, check out our Getting Started with FsHub for Developers documentation!
When making API requests, you should specify the token as a HTTP header, named should be X-Pilot-Token and its value should be the token in a string.
Optionally, if you can not set a Header for some reason, you can instead specify the X-Pilot-Token as a URL parameter like so: ?X-Pilot-Token={TOKEN_HERE}. The preferred option however is to set it as a HTTP Header.
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."
}
}
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.
The maximum limit per page is currently 100 records. Providing a limit beyond that will not fail your request, but will only return 100 items.
We are currently working on a exposing a Swagger UI for the v3 endpoints.
For the time being, please refer to the FsHub Developer Documentation Archive here.
Perhaps you can not get an API working as you like, or you need some help with your project? Check out our Developers Section on the FsHub Forums for threads similar to yours, or simply make one for the community or staff to help you out!
If you need to report an issue with the API, you can also Contact Us directly