API (application programming interface) lets clients integrate FMS with their systems, pull and push data about various entities.
The client makes HTTP requests to the system, providing information about the intended action. HTTP commands usually used in an API:
- GET – Read resource;
- POST – Change resource state;
Requested content is provided in JSON format with UTF-8 encoding. If some other format is used, it is specified in the method description.
HTTP status code identifies the status of the request – for successful requests, status code 200 is returned. Along with this response, requested information from the server will be received. Responses will differ depending on the type of API used. API responses for different API types are described in the according sections.
If an error occurred with the sent request, the system will return a response message with a status code. Common error codes:
- Code 400 – Bad request – API request was not recognized.
- Code 401 – Unauthorized – This means that the authentication credentials are missing or incorrect;
- Code 403 – Forbidden – This means the client has no right to access the requested resource or perform the requested action ;
- Code 404 – Not found – This means that the requested resource was not found.
- Code 500 – Internal server error – please contact your providers tech support.
Error codes provide some general information about the type of error, thus allowing the user to identify the root of the problem.
Some APIs have optional elements (parameters) in their response, optional parameters can be skipped by the system for various reasons (no data, bad data, response time out, etc.). A user must not assume that certain optional data will always be included in a response.
All APIs have one single limitation:
- No more than 1000 requests per minute.
This limitation is valid for all FMS existing APIs.
API authentication and authorization is required to control API usage for different clients and their integration with different systems. In order to make an authorized request to system APIs, clients’ requesting application must first obtain an API_key on behalf of the system web user.
Clients can obtain an API key only by directly contacting their services providers’ technical support. API key consists of randomly generated letters, numbers and symbols.
Example of a request using an API_key:
If the API_key is expired, removed or simply disabled, the system will return the following response:
API endpoints, request parameters and responses can be previewed in “Swagger” through this link: https://api.fm-track.com
It is always necessary to specify an API version in all types of APIs.
Because of the constant development of both the API and the system from where it requests the information, users can sometimes receive parameters not listed in the descriptions. It is recommended to simply ignore unknown parameters which are not documented in each APIs description.
Versioning and compatibility
The API solution is constantly updated, improved and otherwise modified, therefore it is necessary to understand what does “Compatibility” mean and how it affects the user when using the API solution.
When an API is updated one of the following two options happens:
- The API backwards compatible – this means that the changes made will not affect the workflow of the API in any way, thus no new version is created.
- The API is not backwards compatible – this means that some of the API components have been changed to no longer work the same way it worked before. In this case, a new version of the API is released.
What is considered a backwards-compatible API version:
- New API resource was added;
- New optional request parameters were added to the existing API
- New properties were added to the existing API responses.
- The order of the properties was changed in existing API responses.
- Changing the length or format of object IDs or other opaque strings.
The user can safely assume that the object IDs the system generates will never exceed 255 characters, but the user should be able to handle IDs with a potential length of 255 characters. For example, the user is using MySQL, IDs should be stored in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).
- Adding new ENUM types. – any system should gracefully handle any unfamiliar ENUM types. If for example the type changes from [Private, Business] to [Private, Work, Business] it should not make any effect for the system.