Using the API - basic principles¶
All the material here assumes that you already have access to an MFL test environment.
See The API sandbox and Installing for evaluation or Installing for development for information on how to get access to a test environment.
The MFL v2 project subscribes to the API First approach. It is built to interoperate. We “eat our own dog food” by insisting that the official user interfaces be just one more set of API clients, with no special privileges.
This guide is for the authors of client applications ( applications that consume the RESTful web e.g. The service catalog ). Those who would like to make changes to the MFL API server code itself should refer to the Workflow guide.
The MFL 2 API is “RESTish”. We subscribe to the principles of REST but are not pedantic about it. It is built using the excellent Django REST Framework.
HTTP and HTTPS¶
All API actions are based on HTTP and its verbs e.g. GET
and POST
.
HTTP Verb | Description |
---|---|
HEAD | Used to retrieve header information about a resource |
GET | Used to retrieve a resource and for any read-only operation |
POST | Used to create a resource and sometimes to change it |
PUT | Used to mutate an existing resource. We, however, encourage the use of PATCH instead of PUT whenever possible. |
PATCH | Used to edit an already existing resource |
DELETE | Used to delete an already existing resource |
Production instances should always run over HTTPS.
Data Format¶
The MFL API server supports JSON for all API endpoints.
Some endpoints support CSV and Excel output. This will be indicated in the relevant sections of the documentation.
The preferred data format is JSON. We strongly encourage you to use JSON - you will find it to be more reliable, since it is the format used by the official front-ends and is therefore extensively tested.
In order to request a specific format, you will need to learn how to use content negotiation .
Content Negotiation using headers¶
Send the correct Accept
header. For example:
To get json
curl -i -H “Accept: application/json” -H “Content-Type: application/json” http://localhost:8000/api/common/contacts/
To get csv
curl -i -H “Accept: application/csv” -H “Content-Type: application/csv” http://localhost:8000/api/common/contacts/
To get a resource in Microsoft Excel format
curl -i -H “Accept: application/xlsx” -H “Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet” http://localhost:8000/api/common/contacts/
Please note that the examples above do not factor in Authentication and authorization.
Content negotiation using query parameters¶
Append a ?format=<>
GET
parameter. For example:
- to get JSON ( the default ), append
?format=json
to the URL- to get CSV append
?format=csv
to the URL- to get Excel, append
?format=excel
to the URL
Common fields¶
All MFL resources have the following fields:
Field | Description |
---|---|
id |
A UUID. This is the database record’s primary key. |
created |
An ISO 8601 timestamp ( UTC time zone ) that indicates when the resource was created |
updated |
An ISO 8601 timestamp ( UTC time zone ) that shows when the last update occured |
active |
A boolean; will be set to false when the record is retired |
deleted |
A boolean; will be set to true when the record is removed. The API will in-fact not return deleted items by default. |
created |
The ID of the user that created the record. The user model is the only one with non UUID primary keys. |
updated |
The ID of the user that last updated the record. |
The example listing below clearly shows the shared fields:
{
"count": 5,
"next": null,
"previous": null,
"results": [
{
"id": "16f7593f-0a21-41b6-87f1-ef2c4ec7e029",
"created": "2015-05-03T02:30:26.345994Z",
"updated": "2015-05-03T02:30:26.346007Z",
"deleted": false,
"active": true,
"name": "POSTAL",
"description": null,
"created_by": 1,
"updated_by": 1
},
{
"id": "f4eaf905-be91-4050-b154-600e31510306",
"created": "2015-05-03T02:30:26.342216Z",
"updated": "2015-05-03T02:30:26.342229Z",
"deleted": false,
"active": true,
"name": "FAX",
"description": null,
"created_by": 1,
"updated_by": 1
},
{
"id": "f4e835d3-e6a4-4d2d-9d37-344a3da1bb0a",
"created": "2015-05-03T02:30:26.338468Z",
"updated": "2015-05-03T02:30:26.338481Z",
"deleted": false,
"active": true,
"name": "LANDLINE",
"description": null,
"created_by": 1,
"updated_by": 1
},
{
"id": "68281bd2-d616-418d-ab01-616a225b643b",
"created": "2015-05-03T02:30:26.334496Z",
"updated": "2015-05-03T02:30:26.334510Z",
"deleted": false,
"active": true,
"name": "MOBILE",
"description": null,
"created_by": 1,
"updated_by": 1
},
{
"id": "b2ce5bc9-0c73-4586-b5d2-e96c69b90b85",
"created": "2015-05-03T02:30:26.328938Z",
"updated": "2015-05-03T02:30:26.328956Z",
"deleted": false,
"active": true,
"name": "EMAIL",
"description": null,
"created_by": 1,
"updated_by": 1
}
]
}
These fields are exposed via filters in most list endpoints. The examples below show those filters in use:
Filter | Example and examples |
---|---|
updated_before |
Returns results where the date is less than or equal to the supplied timestamp. An example of a valid query is GET /api/facilities/facilities/?updated_before=2014-05-06T10:36:45.112488Z |
updated_after |
Returns results where the date is greater than or equal to the supplied timestamp. An example of a valid query is GET /api/facilities/facilities/?updated_after=2014-05-06T10:36:45.112488Z |
created_before |
Same as for updated_before , but operates on creation timestamps |
created_after |
Same as for updated_after , but operates on creation timestamps |
is_active |
Can be used to retrieve active or inactive results only e.g GET /api/facilities/facilities/?is_active=false |
Note
Filters can be combined / chained.
Documentation examples¶
All the examples in this documentation will use the recommended JSON format.
Data notations¶
The example below demonstrates the manner in which example JSON payloads in the documentation should be interpreted:
{
"name": "John Doe",
"gender": "M",
"age": 33,
"houses": [
{
"city": "Nairobi",
"type": "Flat"
},
{
"city": "Mombasa",
"type": "Bungalow"
}
],
"phone": {
"work": "8781923",
"home": "213789123"
}
}
This table describes the data above
Property | Type | Description |
---|---|---|
name | string | Name of the person |
age | integer | Age of the person |
gender | string | Gender of the person |
houses | list of objects | A list of houses the person owns |
houses[ ].city | string | The city in which the house is in |
houses[ ].type | string | The type of the house |
phone | object | The person’s phone numbers |
phone.work | string | Work phone number |
phone.home | string | Home phone number |
The [ ] notation is used to indicate a property of every object in a list.
For example, houses[ ].city
means every object in the list houses
has a property called city
.
Data types¶
The data types are standard JSON. The MFL API uses UUIDs for its primary keys.
Data type | JSON Representation | Description |
---|---|---|
string | string | A sequence of zero or more characters wrapped in double quotes. |
object | object | A collection of name-value pairs wrapped in curly braces : { and } |
list | array | A collection of values |
boolean | boolean | Represents truthy values and falsy values.Valid values are true and false |
null | null | Represents null values |
integer | integer | Integer values |
decimal | string | Precision decimal values represented as strings |
uuid | string | A string of 32 characters used as a unique identifier (UUIDs) |
datetime | string | A string representing date and time values (Dates and times) |
url | string | A string representing the location of a network resource |
URLs¶
URLs in this document shall be written in shortform, excluding the scheme and domain (or IP) from which MFL can be accessed.
For a production system, the scheme shall always be https
, unless
otherwise specified.
For example, if MFL is running from the IP 192.168.1.56, a full URL could be https://192.168.1.56/api/common/contacts/
. In the documentation, the
URL shall be written as /api/common/contacts/
, exluding the scheme and
domain (or IP).
Note
All URLs have a trailing slash unless specified otherwise.
For example, the url https://192.168.1.56/v1/claims/
is not equivalent
to the url https://192.168.1.56/v1/claims
.
The latter will result in a HTTP 404
(Not Found) response
URL Parameters¶
Any API endpoints that support url parameters shall be specified in the following format:
/api/common/counties/<value>/
For example to retrieve a county by its ID ( UUID ), the URL shall be specified as:
/api/common/counties/<id>/
e.g. /api/common/counties/89d8f3dd698b46e6a052f355a231858d/
URL Query Parameters¶
Any API endpoints that support query parameters shall be specified in the following format:
/api/common/counties/?name=<value>
For example to query the county endpoint by name
, the URL shall be
specified as:
/api/common/counties/?name=<name>
e.g. /api/common/counties/?name=Nairobi
Dates and times¶
All dates and times shall be represented as datetime strings in ISO 8601 format i.e.
YYYY-MM-DDTHH:MM:SSZ
e.g. 2015-03-30T15:23:89Z
If timezone is to be included, the timezone shall be UTC
, thus the format becomes
YYYY-MM-DDTHH:MM:SS+0000
e.g. 2015-03-30T15:23:89+0000
Any date that does not have a timezone shall be assumed to be UTC
.
UUIDs¶
UUIDs are used as unique record identifiers for each record in MFL. All UUIDs used in MFL are version 4 UUIDs.
HTTP Errors¶
- 400 (Bad Request)
- This error occurs if the request given to the server is malformed or does not meet certain criteria e.g. invalid data.
- 401 (Unauthorized)
- The request to access a resource was unauthorized. (Authentication and authorization)
- 403 (Forbidden)
- The authorized user does not have permission to access a resource (Authentication and authorization)
- 404 (Not found)
- The requested resource was not found
- 410 (Gone)
- The requested resource has been removed
- 500 (Server Error)
- A server error has occurred
Pagination¶
Endpoints that return multiple items will be paginated with a page size of 25 by default. All endpoints returning a list of items shall have the following format:
GET /api/common/constituencies/?page=2
{
"count": 290,
"next": "http://localhost:8000/api/common/constituencies/?page=3",
"previous": "http://localhost:8000/api/common/constituencies/",
"results": [
{
... // list of items requested, in this case constituencies
]
}
A client can request a larger page size by specifying the page_size
parameter
e.g /api/common/contacts/?page_size=100
. There page size limit is selected at
server configuration time; it will usually be around 1000 items.
Audit trail¶
The API server provides an audit trail for all non third-party resources.
This audit trail can be accessed on detail endpoints by appending an
include_audit=true
query parameter.
For example, if there was a contact with the id
28d2a0c8-40f4-4686-97d0-d7c6f453fcb3
, a GET
request to
/api/common/contacts/28d2a0c8-40f4-4686-97d0-d7c6f453fcb3/?include_audit=true
would return a payload that has a revisions key that contains a
representation of every past revision of that specific contact.
Search¶
Every list endpoint supports full text search. Search is implemented as a filter, using the search query parameter.
For example, to search for contacts that have the word “meru” in them, the
query would be /api/common/contacts/?search=meru
.