The Keaz API is REST-like and primarily uses JSON as the data encapsulation mechanism. Resources are accessed as top-level path components as detailed in the Resources sections below.
Fequently throughout this documentation, references are made to things like { VEHICLE HASH } or { USER HASH }. This is a means of referring to the basic hash for a resource as it is stored in the datastore. It generally contains all of the resource’s fields and a few house-keeping fields like id and location.
Note
Some fields are automatically removed prior to being returned. An example of this is the password field in a { USER HASH }.
Each resource is comprised of one or more fields. There are two attributes a field may have which affect its usage:
The documentation for each resource contains the details of the required fields and which of the above conditions may apply.
Fields are not typed and excluding validation expressions, are not checked for appropriateness by the API layer. Submitted, and, for the most part, retrieved data is handled as a string.
When manipulating or fetching bookings, dates and times are provided through the path to the resource.
GET /branch/1/bookings/2014-01-01/08:00/2014-01-02/06:00
An attempt by the API to interpret the date format automatically will occur, but for explicitness, it is best to use ISO dates. All times must be devoid of minutes or seconds - all bookings work on an hourly basis.
Within the documentation, any path which requires date time strings will use the shorthand DATETIMEPATH
GET /vehicle/4/bookings/DATETIMEPATH
All requests require the presence of a token query parameter:
GET http://server.name/resource/ID?token=TOKEN_VALUE
Tokens can be retrieved from the /login endpoint in exchange for a valid email and password.
Operation: POST /login
Request body:
{
'email': 'someone@somewhere.fake',
'password': 'hereitisbigboy'
}
Status: 200 OK
Response body:
{
"token": "somelongandunreadablevalue"
}
The login path also supports GET requests. Currently this is used to serve data required for logging in such as company assets.
Each request made to the api passes through an authorization handler with the exceptions of the following paths:
In addition, a required HTTP header HTTP-X-Source-Host must be passed in which contains the subdomain for the request. This is how requests are tied to companies.
Each user is assigned a set of permissions and those permissions roll-out to a list of low-level API operations. Refer to the code in api/utils/__init__.py for the gory details.
The requested path and action (HTTP verb) are compared to the list of permissions to determine whether or not the user is allowed access. In the event that a user is not allowed access, a 401 Forbidden is raised.
Most GET requests support the following query paramters:
Note
The use of q is resource-specific in terms of the field which will be filtered and the documentation for each resource reflects this. A good rule of thumb, however, is to assume the filtering will be done on the name field for the resource.
Operation: GET /companies?q=bang
Status: 200 OK
Response body:
[
{'name': 'Big Bang Corp', ... },
{'name': 'BangBang Guns LTD', ...},
...
]
By performing a GET against /login/reset along with an email in the query string, password resets can be requested. An email is sent with a ticket that can be posted back to /login/reset/TICKET along with a field called password in the request body.