Akvo Flow API v1

The Akvo Flow REST API is a read-only API that enables an organization/user to use a third party application to request data gathered with Akvo Flow. Being a read-only API means that we currently only support GET requests.

The latest version of Flow's API is v2. Here you can find all the documentation to get you started.Flow API repo here

Akvo Flow API v1 in deprecation

Having v2 of Flow’s API, however, means that v1 will no longer be available. As of 30th June 2018, v1 of Flow’s API will be removed and support will not longer be provided by our team. During the sunset period, we will not make any updates or provide support for setting up v1 of Flow’s API. If you want to continue using your Flow data in another system via the API, you’ll need to switch your implementation and reconfigure it to be based on v2 of the API.

For more details on the sunset period and deprecation of v1 check here

Archived documentation

Here you can find the documentation for v1 of Flow's API. Please note that the v1 will no longer be supported from 30 June 2018 onwards.

Authentication

Before an application can communicate with the Akvo Flow API proper credentials are needed. The credentials consists of a pair of keys: one secret key and one access key. It is important to keep the secret key private, otherwise unauthorized access to the FLOW instance is a possibility. The credentials can created by a user with 'Admin' role in the FLOW dashboard.

Authentication with the server is handled via HMAC. A similar approach to authentication is used by Amazon Web Services. The idea of HMAC authentication is that the client computes a signature based on the HTTP request with the secret key. The server can access the secret key given an access key and can therefore calculate a signature the same way as the client did. If the resulting signature is the same as the one which was sent by the client the server can be certain of the origin of the request and the client is assumed to be authenticated.

Three parts are needed to compute the signature:

• The HTTP method, which will always be GET in our case as we currently only support reading.
• The epoch time of the request
• The resource that the application wants to access prefixed with "/api/v1" and excluding any query parameters.

As an example, suppose you want to access the resource /surveys, the string to sign will be

GET
1408619129
/api/v1/surveys

The HTTP request itself must contain two headers:

• Date: <epoch-time>
• Authentication: <access-key>:<signature>

Examples of how to authenticate with the API are available in several programming languages at https://github.com/akvo/akvo-flow-api-examples.

Available resources

The following resources are available:

• /survey_groups
• /surveys
• /question_groups
• /questions
• /question_answers
• /survey_assignments
• /surveyed_locales
• /survey_instances
• /device_groups
• /devices

For version 1 of the API the resource must be prefixed with /api/v1. A request for all devices would consist of a GET request (with the correct authentication headers) to

https://<flow-instance>/api/v1/devices

Examples

You can find all the examples in the Flow API Examples repository.