Http Api
Last Updated: 2023-10-29 02:01:34
Similar to the concept of inline variables, responses also have general datasets returned regardless of the API call. The general response variables are important because they identify the status of your API call, specify possible actions to take and indicate whether the task is queued.
Sometimes a task is expected to take an above average time to finish and other times it needs to be isolated to accommodate busy periods. Either way, the API call would be queued. It's important to understand that a queued task is not complete and is waiting to be processed. This means you'll receive a positive response in the general response variables but must poll for status updates using a queue reference id provided to get the actual results.
An important part of API implementation is to start at the beginning and rule out network or connection issues. This can easily be done by checking the HTTP header and confirming you are receiving a status of 200 or 401. An HTTP status of 401 means the API endpoint you are accessing requires authentication or an authenticated client token has expired.
The following is a list of the most common HTTP statuses you will encounter.
- HTTP_BAD_REQUEST = 400
- HTTP_UNAUTHORIZED = 401
- HTTP_FORBIDDEN = 403
- HTTP_NOT_FOUND = 404
- HTTP_CONFLICT = 409
Before discussing authentication, specific API calls and responses, we need to go over the general response variable so you can create an effective library.
All API calls return data in the form of a JSON string, however, a 401 status yields an empty string and should not be checked. The following outlines the data variables received from a typical API call.
{"status":1,"count":2,"error":0,"messages":[],"results":{"Test":"6919","Test2":"19"},"params":{"api":"system"}}
Status
Not to be confused with the HTTP header status. This indicates whether the API call successfully completed with or without errors. The values are 0 or 1. 0 indicates failure and 1 indicates success.
Error
Is set to 1 indicating an error occurred.
Messages
If an error occurs, this will contain an array of messages.
Count
This is related to results and is set to the number of variables received or the number of items in a list response.
Results
The result data is represented in two ways. A key/value pair or an array for list responses.
Params
The list of parameters the API call received.
Note: General response variables are in lower case, however, the results may not be.
There are two fundamental processes which need specific handling. They are authentication, identifying and polling for queued task responses. This is an overview, we'll get to the actual API call in detail later.
Authentication
Before making API calls you need to authenticate your developer, manager or partner API token by passing your credentials to receive a client token which then can be used in subsequent calls. Token authentication is done by passing them through HTTP header variables, specifically X-Api-Token and X-Api-Client-Token.
For example, pass your developer token via the Http X-Api-Token variable to /api/system/access/authorize and use your username and password as parameters. The response will contain a variable called ClientToken in the results key/value dataset. This key can then be used in subsequent calls via the HTTP variable X-Api-Client-Token.
Note: You must still pass the developer token X-Api-Token along with X-Api-Client-Token.
Queue References & Polling Results
An API call may queue it's task either by design or system load. There are two scenarios in order to identify a queued task and this depends on whether the API call has multiple stages of it's execution.
It doesn't matter if the expected response is in key/value pair of list format. A queued task will have a variable called QueueReference in its response, however, if there are multiple stages of execution then a response is usually in list format with each list item containing the QueueReference variable.
When the QueueReference variable is identified, you must make a call to /api/system/status/queue and pass the value of QueueReference as the parameter ReferenceId. The response will either be contain a couple variables including Status, Error and Response. Let's go over these.
Status
The status of the queued task itself. It can be one of the following.
- Initialized or still being processed.
- Completed in which case you can access the results are in the Response field.
- An error occurred in which case it's logged in the Error field.
Error
The error will contain a list of error messages.
Response
Contains the results of the originating api call.
Note: Fliddo offers an official PHP bootstrap wrapper of the HTTP API for those in a PHP environment. Other languages are in development including C# and Java.
