ODK Central API¶
ODK Central Backend is a RESTful API server that provides key functionality for creating and managing ODK data collection campaigns. It couples with Central Frontend, an independent frontend interface, to form ODK Central, a complete user-installable ODK server solution. While Central Frontend is the primary consumer of the ODK Central API, the API this server provides is fully public and generic: anything that can be done in the user interface can be done directly via the API.
You can read on for a brief overview of the main concepts and how they fit together, or jump to one of the sections for a more in-depth description.
API Overview
To use the API to manage your data collection campaigns, you will need to authenticate with it, so it knows who you are and what you are allowed to do. We provide multiple methods to authenticate with the API, as well as different models for managing the identities and permissions in your system. Human staff users that manage data collection campaigns are Users, and mobile devices are granted access via App Users, and each of these account types have their own way of authenticating. But, these concepts both boil down to Actors, which are how the API actually thinks about authentication and permissioning.
The /users resource can be used to create, manage, and delete Users. These are the staff members who have administrative rights on your server, some projects, or both. Additional tasks like resetting a user's password are also available. You could use this API to, for example, synchronize accounts with another system or mass-provision Users.
Actors (and thus Users) may be granted rights via Assignments. In short, a Roles API is available which describes the defined Roles within the system, each of which allows some set of verbs. The Assignments APIs, in turn, assign Roles to certain Actors upon certain system objects. More information on these may be found below, under Accounts and Users.
The rest of system is made up mostly of standard REST resources and subresources, nested under and partitioned by the /projects Projects resource. Forms, submissions to those forms, attachments on forms or submissions, and App Users ("App Users" in the management interface), are all subresources within /projects. This way, each project is essentially its own sandbox which can be managed and manipulated at will.
The /projects/:id/app-users subresource can be used to create, manage, and delete App Users.
The /projects/:id/forms resource and its subresource /projects/:id/forms/…/submissions provide full access to create, manage, and delete Forms and Submissions to those Forms. Each Form is a single ODK XForms form, and many Submissions (filled-out forms, also sometimes called Instances) may be attached to each Form. These resources are created by sending XML in the ODK XForms format instead of JSON. One can also retrieve all the multimedia attachments associated with any submission through the /projects/:id/forms/…/submissions/…/attachments subresource.
Forms and their submissions are also accessible through two open standards specifications that we follow:
The OpenRosa standard allows standard integration with tools like the ODK Collect mobile data collection app, or various other compatible tools like Enketo. It allows them to see the forms available on the server, and to send new submissions to them.
The OData standard allows data to be shared between platforms for analysis and reporting. Tools like Microsoft Power BI and Tableau are examples of clients that consume the standard OData format and provide advanced features beyond what we offer. If you are looking for a straightforward JSON output of your data, or you are considering building a visualization or reporting tool, this is your best option.
Projects can also contain Entities, data objects that can be created by Submissions and shared between Forms to support workflows with multiple steps. Entities are organized into named Datasets and are managed from the /projects/:id/datasets resource.
⚠️ In this API and in the related ODK XForms specification, collections of
Entitiesare referred to asDatasets. The term "Entity List" is used for this concept in the Central frontend UI, user documentation, and all other text intended for end users who are not developers.
Finally, system information and configuration is available via a set of specialized resources. Currently, you may set the Usage Reporting configuration and retrieve Server Audit Logs.