1.6 Browsing the Web API

The entry point for browsing the Web API is /api/ . This resource provide links to all available resources. Four resource representation formats are consistently available for all resources: HTML, XML, JSON and JSONP. Some resources will have other formats available, like MS Excel, PDF, CSV and PNG. To explore the API from a web browser, navigate to the /api/ entry point and follow the links to your desired resource, for instance /api/dataElements . For all resources which return a list of elements certain query parameters can be used to modify the response:

Query parameters
Param Option values Default option Description
paging true | false true Indicates whether to return lists of elements in pages.
page number 1 Defines which page number to return.
pageSize number 50 Defines the number of elements to return for each page.
order property:asc/iasc/desc/idesc Order the output using a specified order, only properties that are both persisted and simple (no collections, idObjects etc) are supported. iasc and idesc are case insensitive sorting.

An example of how these parameters can be used to get a full list of data element groups in XML response format is:

/api/26/dataElementGroups.xml?links=false&paging=false

You can query for elements on the name property instead of returning full list of elements using the query query variable. In this example we query for all data elements with the word “anaemia” in the name:

/api/26/dataElements?query=anaemia

You can get specific pages and page sizes of objects like this:

/api/26/dataElements.json?page=2&pageSize=20

You can completely disable paging like this:

/api/26/indicatorGroups.json?paging=false

To order the result based on a specific property:

/api/26/indicators.json?order=shortName:desc

You can find an object based on its ID across all object types through the identifiableObjects resource:

/api/26/identifiableObjects/<id>

1.6.1 Translation

DHIS2 supports translations of database content, such as data elements, indicators and programs. All metadata objects in the Web API have properties meant to be used for display / UI purposes, which includes displayName , displayShortName and displayDescription .

Translate options
Parameter Values Description
translate true | false Translate display* properties in metadata output (displayName, displayShortName, displayDescription, and displayFormName for data elements). Default value is true.
locale Locale to use Translate metadata output using a specified locale (requires translate=true).

1.6.2 Translation API

The translations for an object is rendered as part of the object itself in the translations array. Note that the translations array in the JSON/XML payloads are normally pre-filtered for you, which means they can not directly be used to import/export translations (as that would normally overwrite locales other than current users).

Example of data element with translation array filtered on user locale:

{
  "id": "FTRrcoaog83",
  "displayName": "Accute French",
  "translations": [
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    }
  ]
}

Example of data element with translations turned off:

{
  "id": "FTRrcoaog83",
  "displayName": "Accute Flaccid Paralysis (Deaths < 5 yrs)",
  "translations": [
    {
      "property": "FORM_NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "Accute Flaccid Paral"
    },
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "DESCRIPTION",
      "locale": "en_FK",
      "value": "aa"
    }
  ]
}

Note that even if you get the unfiltered result, and are using the appropriate type endpoint i..e /api/26/dataElements we do not allow updates, as it would be too easy to make mistakes and overwrite the other available locales.

To read and update translations you can use the special translations endpoint for each object resource. These can be accessed by GET or PUT on the appropriate /api/26/<object-type>/<object-id>/translations endpoint. As an example, for a data element with identifier FTRrcoaog83 you could use /api/26/dataElements/FTRrcoaog83/translations to get and update translations. The fields available are property with options NAME , SHORT_NAME , DESCRIPTION , the locale which supports any valid locale ID and the the value itself.

Example of NAME property for French locale:

{
  "property": "NAME",
  "locale": "fr",
  "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
}

This payload would then be added to a translation array, and sent back to the appropriate endpoint:

{
  "translations": [
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
    }
  ]
}

For a an data element with ID FTRrcoaog83 you can PUT this to /api/26/dataElements/FTRrcoaog83/translations . Make sure to send all translations for the specific object and not just for a single locale (if not you will potentially overwrite existing locales for other locales).

1.6.3 Web API versions

The Web API is versioned starting from DHIS 2.25. The API versioning follows the DHIS 2 major version numbering. As an example, the API version for DHIS 2.25 is 25 .

You can access a specific API version by including the version number after the /api component, as an example like this:

/api/26/dataElements

If you omit the version part of the URL, the system will use the current API version. As an example, for DHIS 2.25, when omitting the API part, the system will use API version 25. When developing API clients it is recommended to use explicit API versions (rather than omitting the API version), as this will protect the client from unforeseen API changes.

The last three API versions will be supported. As an example, DHIS version 2.27 will support API version 27, 26 and 25.

Note that the metadata model is not versioned, and that you might experience changes e.g. in associations between objects. These changes will be documented in the DHIS2 major version release notes.