API design

Introduction

The API documentation linked here is design documentation. Final API documentation will be generated automatically from the API implementation using a tool like Swagger or Docbox, but we need to write documentation in advance for design purposes as well. What this means is that the documentation here is a basis for discussion, and is not set in stone. Don't rely on what's written here as a guide for how the API works! Once we have API documentation generation set up, we'll link to it from here, but until then the only reliable guide to how the API works is the source code itself.

API segments

• User authentication API
• User management API
• User roles API
• Organizations API
• Projects API
• Spatial units API
• Parties API
• Relationships API
• Questionnaires API
• Resources API
• GeoODK API

General principles

Versioning

API endpoints must be signed with an API version:

https://api.{host}/{api_version}/…

We will start with v1 and increase versions later when we introduce breaking changes to the API.