Skip to content

OpenAPI

The DHIS2 server can provide an OpenAPI document for its API. This document is created on the fly from analysis of the actual API. It means the document is complete but details may be lost or misrepresented due to limitations in the analysis.

Both JSON and YAML format are supported by all OpenAPI endpoints. YAML should be requested with Accept header of application/x-yaml.

To fetch a single document containing all endpoints of the server use:

GET /api/openapi.json
GET /api/openapi.yaml

OBS! Be aware that this generates a document that is several MBs in size.

A document for a specific endpoint can be accessed by appending either openapi.json or openapi.yaml to an endpoint root path. For example, to generate a document for the /users endpoints use:

GET /api/users/openapi.json
GET /api/users/openapi.yaml

To generate a document with a specific selection of root paths and/or tags the general /openapi endpoint can be used with one or more tag and path selectors.

GET /api/openapi/openapi.json?path=/users&path=/dataElements
GET /api/openapi/openapi.yaml?tag=system&tag=metadata

Available tags are:

  • user
  • data
  • metadata
  • ui
  • analytics
  • system
  • messaging
  • tracker
  • integration
  • login
  • query
  • management

All endpoints that generate a OpenAPI document support the following optional request parameters:

failOnNameClash

When set to true, two or more types of same simple (unqualified) name are considered clashing and the generation fails with an error.

When set false (default), name clashes are resolved by adding numbers to the simple name to make each of them unique. As a result the names are not predictable or stable. Merging simple names with their intended markdown documentation based on name will be broken. This option is meant as a preview feature which should only be used during development.

failOnInconsistency

When set to true, a semantic inconsistency in the declaration causes the generation to fail with an error. Usually this indicates a programming mistake. For example, declaring a field both as required and having a default value.

When set to false, a semantic inconsistency is logged as warning but the generation proceeds. This might produce a document that contradicts itself semantically but is valid formally.