All the material here assumes that you already have access to an MFL test environment.
See 07_sandbox
and 01_evaluator_install
or 02_developer_install
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. 09_services
). Those who would like to make changes to the MFL API server code itself should refer to the 14_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.
All API actions are based on HTTP and its verbs e.g. GET
and POST
.
HTTP Verb | Description |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Production instances should always run over HTTPS.
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 .
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 05_authentication
.
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
All resources have the following fields:
Field | Description |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|
|
|
|
|
|
|
|
|
|
|
Note
Filters can be combined / chained.
All the examples in this documentation will use the recommended JSON format.
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 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
.
The data types are standard JSON. The MFL API uses UUIDs for its primary keys.
Data type | JSON Representation | Description |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
URLs in this document shall be written in shortform, excluding the scheme and domain (or IP) from which can be accessed.
For a production system, the scheme shall always be https
, unless otherwise specified.
For example, if 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
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/
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
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 are used as unique record identifiers for each record in . All UUIDs used in are version 4 UUIDs.
- 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. (
05_authentication
)- 403 (Forbidden)
The authorized user does not have permission to access a resource (
05_authentication
)- 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
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.
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.
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
.