Overview

The Web API is a component which makes it possible for external systems to access and manipulate data stored in an instance of DHIS2. More precisely, it provides a programmatic interface to a wide range of exposed data and service methods for applications such as third-party software clients, web portals and internal DHIS2 modules.

Introduction

The Web API adheres to many of the principles behind the REST architectural style. To mention some few and important ones:

1. The fundamental building blocks are referred to as resources. A resource can be anything exposed to the Web, from a document to a business process - anything a client might want to interact with. The information aspects of a resource can be retrieved or exchanged through resource representations. A representation is a view of a resource's state at any given time. For instance, the reportTable resource in DHIS2 represents a tabular report of aggregated data for a certain set of parameters. This resource can be retrieved in a variety of representation formats including HTML, PDF, and MS Excel.

2. All resources can be uniquely identified by a URI (also referred to as URL). All resources have a default representation. You can indicate that you are interested in a specific representation by supplying an Accept HTTP header, a file extension or a format query parameter. So in order to retrieve the PDF representation of a report table you can supply an Accept: application/pdf header or append .pdf or ?format=pdf to your request URL.

3. Interactions with the API requires the correct use of HTTP methods or verbs. This implies that for a resource you must issue a GET request when you want to retrieve it, POST request when you want to create one, PUT when you want to update it and DELETE when you want to remove it. So if you want to retrieve the default representation of a report table you can send a GET request to e.g. /reportTable/iu8j/hYgF6t, where the last part is the report table identifier.

4. Resource representations are linkable, meaning that representations advertise other resources which are relevant to the current one by embedding links into itself (please be aware that you need to request href in your field filter to have this working. This feature greatly improves the usability and robustness of the API as we will see later. For instance, you can easily navigate to the indicators which are associated with a report table from the reportTable resource through the embedded links using your preferred representation format.

While all of this might sound complicated, the Web API is actually very simple to use. We will proceed with a few practical examples in a minute.

Authentication

The DHIS2 Web API supports two protocols for authentication, Basic Authentication and OAuth 2. You can verify and get information about the currently authenticated user by making a GET request to the following URL:

/api/33/me

And more information about authorities (and if a user has a certain authority) by using the endpoints:

/api/33/me/authorities
/api/33/me/authorities/ALL

Basic Authentication

The DHIS2 Web API supports Basic authentication. Basic authentication is a technique for clients to send login credentials over HTTP to a web server. Technically speaking, the username is appended with a colon and the password, Base64-encoded, prefixed Basic and supplied as the value of the Authorization HTTP header. More formally that is:

Authorization: Basic base64encode(username:password)

Most network-aware development environments provide support for Basic authentication, such as Apache HttpClient and Spring RestTemplate. An important note is that this authentication scheme provides no security since the username and password are sent in plain text and can be easily observed by an attacker. Using Basic is recommended only if the server is using SSL/TLS (HTTPS) to encrypt communication with clients. Consider this a hard requirement in order to provide secure interactions with the Web API.

Two-factor authentication

DHIS2 supports two-factor authentication. This can be enabled per user. When enabled, users will be asked to enter a 2FA code when logging in. You can read more about 2FA here.

OAuth2

DHIS2 supports the OAuth2 authentication protocol. OAuth2 is an open standard for authorization which allows third-party clients to connect on behalf of a DHIS2 user and get a reusable bearer token for subsequent requests to the Web API. DHIS2 does not support fine-grained OAuth2 roles but rather provides applications access based on user roles of the DHIS2 user.

Each client for which you want to allow OAuth 2 authentication must be registered in DHIS2. To add a new OAuth2 client go to Apps > Settings > OAuth2 Clients in the user interface, click Add new and enter the desired client name and the grant types.

Adding a client using the Web API

An OAuth2 client can be added through the Web API. As an example, we can send a payload like this:

{
    "name": "OAuth2 Demo Client",
    "cid": "demo",
    "secret": "1e6db50c-0fee-11e5-98d0-3c15c2c6caf6",
    "grantTypes": ["password", "refresh_token", "authorization_code"],
    "redirectUris": ["http://www.example.org"]
}

The payload can be sent with the following command:

SERVER="https://play.dhis2.org/dev"
curl -X POST -H "Content-Type: application/json" -d @client.json
  -u admin:district "$SERVER/api/oAuth2Clients"

We will use this client as the basis for our next grant type examples.

Grant type password

The simplest of all grant types is the password grant type. This grant type is similar to basic authentication in the sense that it requires the client to collect the user's username and password. As an example we can use our demo server:

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d grant_type=password -d username=admin -d password=district

This will give you a response similar to this:

{
    "expires_in": 43175,
    "scope": "ALL",
    "access_token": "07fc551c-806c-41a4-9a8c-10658bd15435",
    "refresh_token": "a4e4de45-4743-481d-9345-2cfe34732fcc",
    "token_type": "bearer"
}

For now, we will concentrate on the access_token, which is what we will use as our authentication (bearer) token. As an example, we will get all data elements using our token:

SERVER="https://play.dhis2.org/dev"
curl -H "Authorization: Bearer 07fc551c-806c-41a4-9a8c-10658bd15435" "$SERVER/api/33/dataElements.json"

Grant type refresh_token

In general the access tokens have limited validity. You can have a look at the expires_in property of the response in the previous example to understand when a token expires. To get a fresh access_token you can make another round trip to the server and use refresh_token which allows you to get an updated token without needing to ask for the user credentials one more time.

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"
REFRESH_TOKEN="a4e4de45-4743-481d-9345-2cfe34732fcc"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d "grant_type=refresh_token" -d "refresh_token=$REFRESH_TOKEN"

The response will be exactly the same as when you get a token to start with.

Grant type authorization_code

Authorized code grant type is the recommended approach if you don't want to store the user credentials externally. It allows DHIS2 to collect the username/password directly from the user instead of the client collecting them and then authenticating on behalf of the user. Please be aware that this approach uses the redirectUris part of the client payload.

Step 1: Visit the following URL using a web browser. If you have more than one redirect URIs, you might want to add &redirect_uri=http://www.example.org to the URL:

SERVER="https://play.dhis2.org/dev"
$SERVER/uaa/oauth/authorize?client_id=demo&response_type=code

Step 2: After the user has successfully logged in and accepted your client access, it will redirect back to your redirect uri like this:

http://www.example.org/?code=XYZ

Step 3: This step is similar to what we did in the password grant type, using the given code, we will now ask for an access token:

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -u demo:$SECRET -H "Accept: application/json" $SERVER/uaa/oauth/token
-d "grant_type=authorization_code" -d "code=XYZ"

Error and info messages

The Web API uses a consistent format for all error/warning and informational messages:

{
    "httpStatus": "Forbidden",
    "message": "You don't have the proper permissions to read objects of this type.",
    "httpStatusCode": 403,
    "status": "ERROR"
}

Here we can see from the message that the user tried to access a resource I did not have access to. It uses the http status code 403, the http status message forbidden and a descriptive message.

Date and period format

Throughout the Web API, we refer to dates and periods. The date format is:

yyyy-MM-dd

For instance, if you want to express March 20, 2014, you must use 2014-03-20.

The period format is described in the following table (also available on the API endpoint /api/periodTypes)

Relative Periods

In some parts of the API, like for the analytics resource, you can utilize relative periods in addition to fixed periods (defined above). The relative periods are relative to the current date and allow e.g. for creating dynamic reports. The available relative period values are:

THIS_WEEK, LAST_WEEK, LAST_4_WEEKS, LAST_12_WEEKS, LAST_52_WEEKS,
THIS_MONTH, LAST_MONTH, THIS_BIMONTH, LAST_BIMONTH, THIS_QUARTER, LAST_QUARTER,
THIS_SIX_MONTH, LAST_SIX_MONTH, MONTHS_THIS_YEAR, QUARTERS_THIS_YEAR,
THIS_YEAR, MONTHS_LAST_YEAR, QUARTERS_LAST_YEAR, LAST_YEAR, LAST_5_YEARS, LAST_12_MONTHS,
LAST_3_MONTHS, LAST_6_BIMONTHS, LAST_4_QUARTERS, LAST_2_SIXMONTHS, THIS_FINANCIAL_YEAR,
LAST_FINANCIAL_YEAR, LAST_5_FINANCIAL_YEARS

Metadata

Identifier schemes

This section provides an explanation of the identifier scheme concept. Identifier schemes are used to map metadata objects to other metadata during import, and to render metadata as part of exports. Please note that not all schemes work for all API calls, and not all schemes can be used for both input and output. This is outlined in the sections explaining the various Web APIs.

The full set of identifier scheme object types available are listed below, using the name of the property to use in queries:

• idScheme

• dataElementIdScheme

• categoryOptionComboIdScheme

• orgUnitIdScheme

• programIdScheme

• programStageIdScheme

• trackedEntityIdScheme

• trackedEntityAttributeIdScheme

The general idScheme applies to all types of objects. It can be overridden by specific object types.

The default scheme for all parameters is UID (stable DHIS2 identifiers). The supported identifier schemes are described in the table below.

Note that identifier schemes is not an independent feature but needs to be used in combination with resources such as data value import and metadata import.

As an example, to specify CODE as the general id scheme and override with UID for organisation unit id scheme you can use these query parameters:

?idScheme=CODE&orgUnitIdScheme=UID

As another example, to specify an attribute for the organisation unit id scheme, code for the data element id scheme and use the default UID id scheme for all other objects you can use these parameters:

?orgUnitIdScheme=ATTRIBUTE:j38fk2dKFsG&dataElementIdScheme=CODE

Browsing the Web API

The entry point for browsing the Web API is /api. This resource provides 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:

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

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

You can query for elements on the name property instead of returning a 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/dataElements?query=anaemia

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

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

You can completely disable paging like this:

/api/indicatorGroups.json?paging=false

To order the result based on a specific property:

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

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

/api/identifiableObjects/<id>

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 include displayName, displayShortName and displayDescription.

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 is 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/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/<object-type>/<object-id>/translations endpoint.

As an example, for a data element with identifier FTRrcoaog83, you could use /api/dataElements/FTRrcoaog83/translations to get and update translations. The fields available are property with options NAME, SHORT_NAME, DESCRIPTION, locale which supports any valid locale ID and the translated property value.

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 data element with ID FTRrcoaog83 you can PUT this to /api/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).

Web API versions

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

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

/api/33/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.

Metadata object filter

To filter the metadata there are several filter operations that can be applied to the returned list of metadata. The format of the filter itself is straight-forward and follows the pattern property:operator:value, where property is the property on the metadata you want to filter on, operator is the comparison operator you want to perform and value is the value to check against (not all operators require value). Please see the schema section to discover which properties are available. Recursive filtering, ie. filtering on associated objects or collection of objects, is supported as well.

Operators will be applied as logical and query, if you need an or query, you can have a look at our in filter (also have a look at the section below). The filtering mechanism allows for recursion. See below for some examples.

Get data elements with id property ID1 and aggregation operator "sum":

/api/dataElements?filter=id:eq:ID1&filter=aggregationOperator:eq:sum

Get all data elements which have the dataSet with id ID1:

/api/dataElements?filter=dataSetElements.dataSet.id:eq:ID1

Get all data elements with aggregation operator "sum" and value type "int":

/api/dataElements.json?filter=aggregationOperator:eq:sum&filter=type:eq:int

You can do filtering within collections, e.g. to get data elements which are members of the "ANC" data element group you can use the following query using the id property of the associated data element groups:

/api/dataElements.json?filter=dataElementGroups.id:eq:qfxEYY9xAl6

Since all operators are and by default, you can't find a data element matching more than one id, for that purpose you can use the in operator.

/api/dataElements.json?filter=id:in:[fbfJHSPpUQD,cYeuwXTCPkU]

Logical operators

As mentioned in the section before, the default logical operator applied to the filters is AND which means that all object filters must be matched. There are however cases where you want to match on one of several filters (maybe id and code field) and in those cases, it is possible to switch the root logical operator from AND to OR using the rootJunction parameter.

Example: Normal filtering where both id and code must match to have a result returned

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1

Example: Filtering where the logical operator has been switched to OR and now only one of the filters must match to have a result returned

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1&rootJunction=OR

Identifiable token filter

In addition to the specific property based filtering mentioned above, we also have token based AND filtering across a set of properties: id, code, and name (also shortName if available). These properties are commonly referred to as identifiable. The idea is to filter metadata whose id, name, code or short name containing something.

Example: Filter all data elements containing 2^nd in any of the following: id,name,code, shortName

/api/dataElements.json?filter=identifiable:token:2nd

It is also possible to specify multiple filtering values.

Example: Get all data elements where ANC visit is found in any of the identifiable properties. The system returns all data elements where both tokens (ANC and visit) are found anywhere in identifiable properties.

/api/dataElements.json?filter=identifiable:token:ANC visit

It is also possible to combine the identifiable filter with property-based filter and expect the rootJunction to be applied.

/api/dataElements.json?filter=identifiable:token:ANC visit&filter=displayName:ilike:tt1

/api/dataElements.json?filter=identifiable:token:ANC visit
  &filter=displayName:ilike:tt1&rootJunction=OR

Metadata field filter

In many situations, the default views of the metadata can be too verbose. A client might only need a few fields from each object and want to remove unnecessary fields from the response. To discover which fields are available for each object please see the schema section.

The format for include/exclude allows for infinite recursion. To filter at the "root" level you can just use the name of the field, i.e. ?fields=id,name which would only display the id and name fields for every object. For objects that are either collections or complex objects with properties on their own, you can use the format ?fields=id,name,dataSets[id,name] which would return id, name of the root, and the id and name of every data set on that object. Negation can be done with the exclamation operator, and we have a set of presets of field select. Both XML and JSON are supported.

Example: Get id and name on the indicators resource:

/api/indicators?fields=id,name

Example: Get id and name from dataElements, and id and name from the dataSets on dataElements:

/api/dataElements?fields=id,name,dataSets[id,name]

To exclude a field from the output you can use the exclamation ! operator. This is allowed anywhere in the query and will simply not include that property as it might have been inserted in some of the presets.

A few presets (selected fields groups) are available and can be applied using the : operator.

Example: Include all fields from dataSets except organisationUnits:

/api/dataSets?fields=:all,!organisationUnits

Example: Include only id, name and the collection of organisation units from a data set, but exclude the id from organisation units:

/api/dataSets/BfMAe6Itzgt?fields=id,name,organisationUnits[:all,!id]

Example: Include nameable properties from all indicators:

/api/indicators.json?fields=:nameable

Field transformers

In DHIS2.17 we introduced field transformers, the idea is to allow further customization of the properties on the server-side.

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

This will rename the id property to i and name property to n.

Multiple transformers can be used by repeating the transformer syntax:

/api/dataElementGroups.json?fields=id,displayName,dataElements~isNotEmpty~rename(haveDataElements)

Examples

Examples of transformer usage.

/api/dataElements?fields=dataSets~size

/api/dataElements?fields=dataSets~isEmpty

/api/dataElements?fields=dataSets~isNotEmpty

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

/api/dataElementGroups?fields=id,displayName,dataElements~paging(1;20)

# Include array with IDs of organisation units:
/api/categoryOptions.json?fields=id,organisationUnits~pluck

# Include array with names of organisation units (collection only returns field name):
/api/categoryOptions.json?fields=id,organisationUnits~pluck[name]

Metadata create, read, update, delete, validate

All metadata entities in DHIS2 have their own API endpoint which supports CRUD operations (create, read, update and delete). The endpoint URLs follows this format:

/api/<entityName>

The entityName uses the camel-case notation. As an example, the endpoint for data elements is:

/api/dataElements

Create / update parameters

The following request query parameters are available across all metadata endpoints.

Creating and updating objects

For creating new objects you will need to know the endpoint, the type format, and make sure that you have the required authorities. As an example, we will create and update a constant. To figure out the format, we can use the new schema endpoint for getting format description. So we will start with getting that info:

http://<server>/api/schemas/constant.json

From the output, you can see that the required authorities for create are F_CONSTANT_ADD, and the important properties are: name and value. From this, we can create a JSON payload and save it as a file called constant.json:

{
    "name": "PI",
    "value": "3.14159265359"
}

The same content as an XML payload:

<constant name="PI" xmlns="http://dhis2.org/schema/dxf/2.0">
  <value>3.14159265359</value>
</constant>

We are now ready to create the new constant by sending a POST request to the *constants*endpoint with the JSON payload using curl:

curl -d @constant.json "http://server/api/constants" -X POST
  -H "Content-Type: application/json" -u user:password

A specific example of posting the constant to the demo server:

curl -d @constant.json "https://play.dhis2.org/api/constants" -X POST
  -H "Content-Type: application/json" -u admin:district

If everything went well, you should see an output similar to:

{
    "status": "SUCCESS",
    "importCount": {
        "imported": 1,
        "updated": 0,
        "ignored": 0,
        "deleted": 0
    },
    "type": "Constant"
}

The process will be exactly the same for updating, you make your changes to the JSON/XML payload, find out the ID of the constant, and then send a PUT request to the endpoint including ID:

curl -X PUT -d @pi.json -H "Content-Type: application/json"
  -u user:password "http://server/api/constants/ID"

Deleting objects

Deleting objects is very straight forward, you will need to know the ID and the endpoint of the type you want to delete, let's continue our example from the last section and use a constant. Let's assume that the id is abc123, then all you need to do is the send the DELETE request to the endpoint + id:

curl -X DELETE -u user:password "http://server/api/constants/ID"

A successful delete should return HTTP status 204 (no content).

Adding and removing objects in collections

The collections resource lets you modify collections of objects.

Adding or removing single objects

In order to add or remove objects to or from a collection of objects you can use the following pattern:

/api/{collection-object}/{collection-object-id}/{collection-name}/{object-id}

You should use the POST method to add, and the DELETE method to remove an object. When there is a many-to-many relationship between objects, you must first determine which object owns the relationship. If it isn't clear which object this is, try the call both ways to see which works.

The components of the pattern are:

• collection object: The type of objects that owns the collection you want to modify.

• collection object id: The identifier of the object that owns the collection you want to modify.

• collection name: The name of the collection you want to modify.

• object id: The identifier of the object you want to add or remove from the collection.

As an example, in order to remove a data element with identifier IDB from a data element group with identifier IDA you can do a DELETE request:

DELETE /api/dataElementGroups/IDA/dataElements/IDB

To add a category option with identifier IDB to a category with identifier IDA you can do a POST request:

POST /api/categories/IDA/categoryOptions/IDB

Adding or removing multiple objects

You can add or remove multiple objects from a collection in one request with a payload like this:

{
    "identifiableObjects": [
        {
            "id": "IDA"
        },
        {
            "id": "IDB"
        },
        {
            "id": "IDC"
        }
    ]
}

Using this payload you can add, replace or delete items:

Adding Items:

POST /api/categories/IDA/categoryOptions

Replacing Items:

PUT /api/categories/IDA/categoryOptions

Delete Items:

DELETE /api/categories/IDA/categoryOptions

Adding and removing objects in a single request

You can both add and remove objects from a collection in a single POST request to the following URL:

POST /api/categories/IDA/categoryOptions

The payload format is:

{
    "additions": [
        {
            "id": "IDA"
        },
        {
            "id": "IDB"
        },
        {
            "id": "IDC"
        }
    ],
    "deletions": [
        {
            "id": "IDD"
        },
        {
            "id": "IDE"
        },
        {
            "id": "IDF"
        }
    ]
}

Validating payloads

DHIS 2 supports system wide validation of metadata payloads, which means that create and update operations on the API endpoints will be checked for valid payload before allowing changes to be made. To find out what validations are in place for a specific endpoint, have a look at the /api/schemas endpoint, i.e. to figure out which constraints a data element have, you would go to /api/schemas/dataElement.

You can also validate your payload manually by sending it to the proper schema endpoint. If you wanted to validate the constant from the create section before, you would send it like this:

POST /api/schemas/constant

A simple (non-validating) example would be:

curl -X POST -d "{\"name\": \"some name\"}" -H "Content-Type: application/json"
  -u admin:district "https://play.dhis2.org/dev/api/schemas/dataElement"

Which would yield the result:

[
    {
        "message": "Required property missing.",
        "property": "type"
    },
    {
        "property": "aggregationOperator",
        "message": "Required property missing."
    },
    {
        "property": "domainType",
        "message": "Required property missing."
    },
    {
        "property": "shortName",
        "message": "Required property missing."
    }
]

Partial updates

For cases where you don't want or need to update all properties on a object (which means downloading a potentially huge payload, change one property, then upload again) we now support partial update, for one or more properties.

The payload for doing partial updates are the same as when you are doing a full update, the only difference is that you only include the properties you want to update, i.e.:

{
    "name": "Updated Name",
    "zeroIsSignificant": true
}

An example curl command looks like this:

curl -X PATCH -d @file.json -H "Content-Type: application/json"
  -u admin:district "https://play.dhis2.org/dev/api/dataElements/fbfJHSPpUQD"

Metadata export

This section explains the metatada API which is available at /api/metadata. XML and JSON resource representations are supported.

/api/metadata

The most common parameters are described below in the "Export Parameter" table. You can also apply this to all available types by using type:fields=<filter> and type:filter=<filter>. You can also enable/disable the export of certain types by setting type=true|false.

Metadata export examples

Export all metadata. Be careful as the response might be very large depending on your metadata configuration:

/api/metadata

Export all metadata ordered by lastUpdated descending:

/api/metadata?defaultOrder=lastUpdated:desc

Export metadata only including indicators and indicator groups:

/api/metadata?indicators=true&indicatorGroups=true

Export id and displayName for all data elements, ordered by displayName:

/api/metadata?dataElements:fields=id,name&dataElements:order=displayName:desc

Export data elements and indicators where name starts with "ANC":

/api/metadata?filter=name:^like:ANC&dataElements=true&indicators=true

Metadata export with dependencies

When you want to exchange metadata for a data set, program or category combo from one DHIS2 instance to another instance there are three dedicated endpoints available:

/api/dataSets/{id}/metadata.json

/api/programs/{id}/metadata.json

/api/categoryCombos/{id}/metadata.json

/api/dashboards/{id}/metadata.json

These exports can then be imported using /api/metadata.

These endpoints also support the following parameters:

Metadata import

This section explains the metadata import API. XML and JSON resource representations are supported. Metadata can be imported using a POST request.

/api/metadata

The importer allows you to import metadata payloads which may include many different entities and any number of objects per entity. The metadata export generated by the metadata export API can be imported directly.

The metadata import endpoint support a variety of parameters, which are listed below.

An example of a metadata payload to be imported looks like this. Note how each entity type have their own property with an array of objects:

{
    "dataElements": [
        {
            "name": "EPI - IPV 3 doses given",
            "shortName": "EPI - IPV 3 doses given",
            "aggregationType": "SUM",
            "domainType": "AGGREGATE",
            "valueType": "INTEGER_ZERO_OR_POSITIVE"
        },
        {
            "name": "EPI - IPV 4 doses given",
            "shortName": "EPI - IPV 4 doses given",
            "aggregationType": "SUM",
            "domainType": "AGGREGATE",
            "valueType": "INTEGER_ZERO_OR_POSITIVE"
        }
    ],
    "indicators": [
        {
            "name": "EPI - ADS stock used",
            "shortName": "ADS stock used",
            "numerator": "#{LTb8XeeqeqI}+#{Fs28ZQJET6V}-#{A3mHIZd2tPg}",
            "numeratorDescription": "ADS 0.05 ml used",
            "denominator": "1",
            "denominatorDescription": "1",
            "annualized": false,
            "indicatorType": {
                "id": "kHy61PbChXr"
            }
        }
    ]
}

When posting this payload to the metadata endpoint, the response will contain information about the parameters used during the import and a summary per entity type including how many objects were created, updated, deleted and ignored:

{
    "importParams": {
        "userOverrideMode": "NONE",
        "importMode": "COMMIT",
        "identifier": "UID",
        "preheatMode": "REFERENCE",
        "importStrategy": "CREATE_AND_UPDATE",
        "atomicMode": "ALL",
        "mergeMode": "REPLACE",
        "flushMode": "AUTO",
        "skipSharing": false,
        "skipTranslation": false,
        "skipValidation": false,
        "metadataSyncImport": false,
        "firstRowIsHeader": true,
        "username": "UNICEF_admin"
    },
    "status": "OK",
    "typeReports": [
        {
            "klass": "org.hisp.dhis.dataelement.DataElement",
            "stats": {
                "created": 2,
                "updated": 0,
                "deleted": 0,
                "ignored": 0,
                "total": 2
            }
        },
        {
            "klass": "org.hisp.dhis.indicator.Indicator",
            "stats": {
                "created": 1,
                "updated": 0,
                "deleted": 0,
                "ignored": 0,
                "total": 1
            }
        }
    ],
    "stats": {
        "created": 3,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 3
    }
}

Schema

A resource which can be used to introspect all available DXF 2 objects can be found on /api/schemas. For specific resources you can have a look at /api/schemas/<type>.

To get all available schemas in XML:

GET /api/schemas.xml

To get all available schemas in JSON:

GET /api/schemas.json

To get JSON schema for a specific class:

GET /api/schemas/dataElement.json

Icons

DHIS2 includes a collection of icons that can be used to give visual context to metadata. These icons can be accessed through the icons resource.

GET /api/icons

This endpoint returns a list of information about the available icons. Each entry contains information about the icon, and a reference to the actual icon.

{
    "key": "mosquito_outline",
    "description": "Mosquito outline",
    "keywords": ["malaria", "mosquito", "dengue"],
    "href": "<dhis server>/api/icons/mosquito_outline/icon.svg"
}

The keywords can be used to filter which icons to return. Passing a list of keywords with the request will only return icons that match all the keywords:

GET /api/icons?keywords=shape,small

A list of all unique keywords can be found at the keywords resource:

GET /api/icons/keywords

Render type

Some metadata types have a property named renderType. The render type property is a map between a device and a renderingType. Applications can use this information as a hint on how the object should be rendered on a specific device. For example, a mobile device might want to render a data element differently than a desktop computer.

There is currently two different kinds of renderingTypes available:

1. Value type rendering

2. Program stage section rendering

There is also 2 device types available:

1. MOBILE

2. DESKTOP

The following table lists the metadata and rendering types available. The value type rendering has addition constraints based on the metadata configuration, which will be shown in a second table.

Since handling the default rendering of data elements and tracked entity attributes are depending on the value type of the object, there is also a DEFAULT type to tell the client it should be handled as normal. Program Stage Section is LISTING as default.

A complete reference of the previous table can also be retrieved using the following endpoint:

GET /api/staticConfiguration/renderingOptions

Value type rendering also has some additional properties that can be set, which is usually needed when rendering some of the specific types:

The renderingType can be set when creating or updating the metadata listed in the first table. An example payload for the rendering type for program stage section looks like this:

{
    "renderingType": {
        "type": "MATRIX"
    }
}

For data element and tracked entity attribute:

{
    "renderingType": {
        "type": "SLIDER",
        "min": 0,
        "max": 1000,
        "step": 50,
        "decimalPoints": 0
    }
}

Object Style

Most metadata have a property names "style". This property can be used by clients to represent the object in a certain way. The properties currently supported by style is as follows:

Currently, there is no official list or support for icon-libraries, so this is currently up to the client to provide. The following list shows all objects that support style:

• Data element

• Data element category option

• Data set

• Indicator

• Option

• Program

• Program Indicator

• Program Section

• Program Stage

• Program Stage Section

• Relationship (Tracker)

• Tracked Entity Attribute

• Tracked Entity Type

When creating or updating any of these objects, you can include the following payload to change the style:

{
    "style": {
        "color": "#ffffff",
        "icon": "my-beautiful-icon"
    }
}

Indicators

This section describes indicators and indicator expressions.

Aggregate indicators

To retrieve indicators you can make a GET request to the indicators resource like this:

/api/indicators

Indicators represent expressions which can be calculated and presented as a result. The indicator expressions are split into a numerator and denominator. The numerators and denominators are mathematical expressions which can contain references to data elements, other indicators, constants and organisation unit groups. The variables will be substituted with data values when used e.g. in reports. Variables which are allowed in expressions are described in the following table.

The syntax looks like this:

#{<dataelement-id>.<catoptcombo-id>} + C{<constant-id>} + OUG{<orgunitgroup-id>}

A corresponding example looks like this:

#{P3jJH5Tu5VC.S34ULMcHMca} + C{Gfd3ppDfq8E} + OUG{CXw2yu5fodb}

Note that for data element variables the category option combo identifier can be omitted. The variable will then represent the total for the data element, e.g. across all category option combos. Example:

#{P3jJH5Tu5VC} + 2

Data element operands can include any of category option combination and attribute option combination, and use wildcards to indicate any value:

#{P3jJH5Tu5VC.S34ULMcHMca} + #{P3jJH5Tu5VC.*.j8vBiBqGf6O} + #{P3jJH5Tu5VC.S34ULMcHMca.*}

An example which uses a program data element and a program attribute:

( D{eBAyeGv0exc.vV9UWAZohSf} * A{IpHINAT79UW.cejWyOfXge6} ) / D{eBAyeGv0exc.GieVkTxp4HH}

An example which combines program indicators and aggregate indicators:

I{EMOt6Fwhs1n} * 1000 / #{WUg3MYWQ7pt}

An example which uses a reporting rate looks like this:

R{BfMAe6Itzgt.REPORTING_RATE} * #{P3jJH5Tu5VC.S34ULMcHMca}

Another example which uses actual data set reports:

R{BfMAe6Itzgt.ACTUAL_REPORTS} / R{BfMAe6Itzgt.EXPECTED_REPORTS}

An example which uses an existing indicator would look like this:

N{Rigf2d2Zbjp} * #{P3jJH5Tu5VC.S34ULMcHMca}

Expressions can be any kind of valid mathematical expression, as an example:

( 2 * #{P3jJH5Tu5VC.S34ULMcHMca} ) / ( #{FQ2o8UBlcrS.S34ULMcHMca} - 200 ) * 25

Program indicators

To retrieve program indicators you can make a GET request to the program indicators resource like this:

/api/programIndicators

Program indicators can contain information collected in a program. Indicators have an expression which can contain references to data elements, attributes, constants and program variables. Variables which are allowed in expressions are described in the following table.

The syntax looks like this:

#{<programstage-id>.<dataelement-id>} + #{<attribute-id>} + V{<varible-id>} + C{<constant-id>}

A corresponding example looks like this:

#{A03MvHHogjR.a3kGcGDCuk6} + A{OvY4VVhSDeJ} + V{incident_date} + C{bCqvfPR02Im}

Expressions

Expressions are mathematical formulas which can contain references to data elements, constants and organisation unit groups. To validate and get the textual description of an expression, you can make a GET request to the expressions resource:

/api/expressions/description?expression=<expression-string>

The response follows the standard JSON web message format. The status property indicates the outcome of the validation and will be "OK" if successful and "ERROR" if failed. The message property will be "Valid" if successful and provide a textual description of the reason why the validation failed if not. The description provides a textual description of the expression.

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "message": "Valid",
    "description": "Acute Flaccid Paralysis"
}

Organisation units

The organisationUnits resource follows the standard conventions as other metadata resources in DHIS2. This resource supports some additional query parameters.

Get list of organisation units

To get a list of organisation units you can use the following resource.

/api/33/organisationUnits

Get organisation unit with relations

To get an organisation unit with related organisation units you can use the following resource.

/api/33/organisationUnits/{id}

Get organisation units by programs

Purpose-built endpoint to retrieve associations between Programs and Organisation Units. This endpoint is the preferred way to retrieve program org unit associations.

/api/33/programs/orgUnits?programs=<programUid,anotherProgramUid,...>

responses will have the following format:

{
    "<programUid>": [
        "<orgUnitUid>",
        "<orgUnitUid>",
        ...,
        "<orgUnitUid>"
    ],
    "<programUid>": [
        "<orgUnitUid>",
        "<orgUnitUid>",
        ...,
        "<orgUnitUid>"
    ],
    "...": [
        ...,
        ...
    ],
    "<programUid>": []
}

programs with no associated uids (hence accessible by all orgUnits) are returned with an empty array [] of orgUnits.

Data sets

The dataSets resource follows the standard conventions as other metadata resources in DHIS2. This resource supports some additional query parameters.

/api/33/dataSets

To retrieve the version of a data set you can issue a GET request:

GET /api/33/dataSets/<uid>/version

To bump (increase by one) the version of a data set you can issue a POST request:

POST /api/33/dataSets/<uid>/version

DataSet Notification Template

The dataset notification templates resource follows the standard conventions as other metadata resources in DHIS2.

GET /api/33/dataSetNotficationTemplates

To retrieve data set notification template you can issue a GET request:

GET /api/33/dataSetNotficationTemplates/<uid>

To add data set notification template you can issue a POST request:

POST /api/33/dataSetNotficationTemplates

To delete data set notification template you can issue a DELETE request:

DELETE /api/33/dataSetNotficationTemplates/<uid>

JSON payload sample is given below:

{
    "name": "dataSetNotificationTemplate1",
    "notificationTrigger": "COMPLETION",
    "relativeScheduledDays": 0,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "dataSets": [
        {
            "id": "eZDhcZi6FLP"
        }
    ],
    "deliveryChannels": ["SMS"],
    "subjectTemplate": "V{data_name}",
    "messageTemplate": "V{data_name}V{complete_registration_period}",
    "sendStrategy": "SINGLE_NOTIFICATION"
}

Filled organisation unit levels

The filledOrganisationUnitLevels resource provides an ordered list of organisation unit levels, where generated levels are injected into the list to fill positions for which it does not exist a persisted level.

GET /api/33/filledOrganisationUnitLevels

To set the organisation unit levels you can issue a POST request with a JSON payload looking like this.

{
    "organisationUnitLevels": [
        {
            "name": "National",
            "level": 1,
            "offlineLevels": 3
        },
        {
            "name": "District",
            "level": 2
        },
        {
            "name": "Chiefdom",
            "level": 3
        },
        {
            "name": "Facility",
            "level": 4
        }
    ]
}

To do functional testing with curl you can issue the following command.

curl "http://localhost/api/33/filledOrganisationUnitLevels" -H "Content-Type:application/json"
  -d @levels.json -u admin:district

Predictors

A predictor allows you to generate data values based on an expression. This can be used for example to generate targets, thresholds, or estimated values.

To retrieve predictors you can make a GET request to the predictors resource like this:

/api/predictors

Creating a predictor

You can create a predictor with a POST request to the predictors resource:

POST /api/predictors

A sample payload looks like this:

{
    "id": "AG10KUJCrRk",
    "name": "Malaria Outbreak Threshold Predictor",
    "shortName": "Malaria Outbreak Predictor",
    "description": "Computes the threshold for potential malaria outbreaks based on the mean plus 1.5x the std dev",
    "output": {
        "id": "nXJJZNVAy0Y"
    },
    "generator": {
        "expression": "AVG(#{r6nrJANOqMw})+1.5*STDDEV(#{r6nrJANOqMw})",
        "description": "Maximum normal malaria case count",
        "missingValueStrategy": "NEVER_SKIP",
        "slidingWindow": false
    },
    "periodType": "Monthly",
    "sequentialSampleCount": 4,
    "sequentialSkipCount": 1,
    "annualSampleCount": 3,
    "organisationUnitLevels": [4]
}

The output element refers to the identifier of the data element for which to saved predicted data values. The generator element refers to the expression to use when calculating the predicted values.

Predictor expressions

A predictor always has a generator expression that describes how the predicted value is calculated. A predictor may also have a skip test expression returning a boolean value. When the skip test expression is present, it is evaluated in each of the sampled periods to tell whether values from that period should be skipped.

The following variables may be used in either a generator expression or a skip test expression:

Generating predicted values

To run all predictors (generating predicted values) you can make a POST request to the run resource:

POST /api/predictors/run

To run a single predictor you can make a POST request to the run resource for a predictor:

POST /api/predictors/AG10KUJCrRk/run

Program rules

This section is about sending and reading program rules, and explains the program rules data model. The program rules give functionality to configure dynamic behaviour in the programs in DHIS2.

Program rule model

The program rules data model consists of programRuleVariables, programRules and programRuleActions. The programRule contains an expression - when this expression is true, the child programRuleActions is triggered. The programRuleVariables is used to address data elements, tracked entity data values and other data values needed to run the expressions. All programRules in a program share the same library of programRuleVariables, and one programRuleVariable can be used in several programRules' expressions.

Program rule model details

The following table gives a detailed overview over the programRule model.

d2:hasValue('hemoglobin') && #{hemoglobin} <= 7

Program rule action model details

The following table gives a detailed overview over the programRuleAction model.

Program rule variable model details

The following table gives a detailed overview over the programRuleVariable model.

#{myVariable} > 5

Creating program rules

• To perform crud operations, programRules resource is available in API.

To retrieve list of programRules you can do a GET request like this:

/api/programRules

To retrieve single programRule you can do a GET request like this:

/api/programRules/<program_rule_uid>

To save/add single programRule you can do a POST request like this:

/api/programRules/<program_rule_uid>

To update single programRule you can do a PUT request like this:

/api/programRules/<program_rule_uid>

To delete single programRule you can do a DELETE request like this:

/api/programRules/<program_rule_uid>

To retrieve description of programRule condition you can use POST and provide condition string in the POST body.

/api/programRules/condition/description?<program_rule_uid>

Forms

To retrieve information about a form (which corresponds to a data set and its sections) you can interact with the form resource. The form response is accessible as XML and JSON and will provide information about each section (group) in the form as well as each field in the sections, including labels and identifiers. By supplying period and organisation unit identifiers the form response will be populated with data values.

To retrieve the form for a data set you can do a GET request like this:

/api/dataSets/<dataset-id>/form.json

To retrieve the form for the data set with identifier "BfMAe6Itzgt" in XML:

/api/dataSets/BfMAe6Itzgt/form

To retrieve the form including metadata in JSON:

/api/dataSets/BfMAe6Itzgt/form.json?metaData=true

To retrieve the form filled with data values for a specific period and organisation unit in XML:

/api/dataSets/BfMAe6Itzgt/form.xml?ou=DiszpKrYNg8&pe=201401

When it comes to custom data entry forms, this resource also allows for creating such forms directly for a data set. This can be done through a POST or PUT request with content type text/html where the payload is the custom form markup such as:

curl -d @form.html "localhost/api/dataSets/BfMAe6Itzgt/form"
  -H "Content-Type:text/html" -u admin:district -X PUT

Documents

References to files can be stored with the document resource.

A GET request to the documents endpoint will return all documents:

/api/documents

A POST request to the documents endpoint will create a new document:

curl -X POST -d @document.json -H "Content-type: application/json"
  "http://dhis.domain/api/documents"

{
    "name": "dhis home",
    "external": true,
    "url": "https://www.dhis2.org"
}

A GET request with the id of a document appended will return information about the document. A PUT request to the same endpoint will update the fields of the document:

/api/documents/<documentId>

Appending /data to the GET request will return the actual file content of the document:

/api/documents/<documentId>/data

CSV metadata import

DHIS2 supports import of metadata in the CSV format, such as data elements, organisation units and validation rules. Properties for the various metadata objects are identified based on the column order/column index (see below for details). You can omit non-required object properties/columns, but since the column order is significant, an empty column must be included. In other words, if you would like to specify properties/columns which appear late in the column order but not specify certain columns which appear early in the order you can include empty/blank columns for them.

The first row of the CSV file is considered to be a header and is ignored during import. The comma character should be used as a text delimiter. Text which contains commas must be enclosed in double quotes.

To upload metadata in CSV format you can make a POST request to the metadata endpoint:

POST /api/metadata?classKey=CLASS-KEY

The following object types are supported. The classKey query parameter is mandatory and can be found next to each object type in the table below.

Tip

If using curl, the --data-binary option should be used as it preserves line breaks and newlines, which is essential for CSV data.

As an example, to upload a file of data elements in CSV format with curl you can use the following command:

curl --data-binary @data_elements.csv "http://localhost/api/metadata?classKey=DATA_ELEMENT"
  -H "Content-Type:application/csv" -u admin:district

The formats for the currently supported object types for CSV import are listed in the following sections.

Data elements

An example of a CSV file for data elements can be seen below. The first row will always be ignored. Note how you can skip columns and rely on default values to be used by the system. You can also skip columns which you do not use which appear to the right of the ones

name,uid,code,shortname,description
"Women participated skill development training",,"D0001","Women participated in training"
"Women participated community organizations",,"D0002","Women participated in organizations"

Organisation units

A minimal example for importing organisation units with a parent unit looks like this:

name,uid,code,parent
"West province",,"WESTP","ImspTQPwCqd"
"East province",,"EASTP","ImspTQPwCqd"

Validation rules

Option sets

The format for option sets is special. The three first values represent an option set. The three last values represent an option. The first three values representing the option set should be repeated for each option.

optionsetname,optionsetuid,optionsetcode,optionname,optionuid,optioncode
"Color",,"COLOR","Blue",,"BLUE"
"Color",,"COLOR","Green",,"GREEN"
"Color",,"COLOR","Yellow",,"YELLOW"
"Sex",,,"Male",,"MALE"
"Sex",,,"Female",,"FEMALE"
"Sex",,,"Unknown",,"UNKNOWN"
"Result",,,"High",,"HIGH"
"Result",,,"Medium",,"MEDIUM"
"Result",,,"Low",,"LOW"
"Impact","cJ82jd8sd32","IMPACT","Great",,"GREAT"
"Impact","cJ82jd8sd32","IMPACT","Medium",,"MEDIUM"
"Impact","cJ82jd8sd32","IMPACT","Poor",,"POOR"

Option group

Sample OptionGroup CSV payload

optionGroupName,optionGroupUid,optionGroupCode,optionGroupShortName,optionSetUid,optionUid,optionCode
optionGroupA,,,groupA,xmRubJIhmaK,,OptionA
optionGroupA,,,groupA,xmRubJIhmaK,,OptionB
optionGroupB,,,groupB,QYDAByFgTr1,,OptionC

Option Group Set

Sample OptionGroupSet CSV payload

name,uid,code,description,datadimension,optionsetuid
optiongroupsetA,,,,,xmRubJIhmaK
optiongroupsetB,,,,false,QYDAByFgTr1

To add OptionGroups to an imported OptionGroupSet, follow the steps as importing collection membership

Collection membership

In addition to importing objects, you can also choose to only import the group-member relationship between an object and a group. Currently, the following group and object pairs are supported

• Organisation Unit Group - Organisation Unit

• Data Element Group - Data Element

• Indicator Group - Indicator

• Option Group Set - Option Group

The CSV format for these imports are the same

Other objects

An example of category options looks like this:

name,uid,code,shortname
"Male",,"MALE"
"Female",,"FEMALE"

Deleted objects

The deleted objects resource provides a log of metadata objects being deleted.

/api/deletedObjects

Whenever an object of type metadata is deleted, a log is being kept of the uid, code, the type and the time of when it was deleted. This API is available at /api/deletedObjects field filtering and object filtering works similarly to other metadata resources.

Get deleted objects of type data elements:

GET /api/deletedObjects.json?klass=DataElement

Get deleted object of type indicator which was deleted in 2015 and forward:

GET /api/deletedObjects.json?klass=Indicator&deletedAt=2015-01-01

Favorites

Certain types of metadata objects can be marked as favorites for the currently logged in user. This applies currently for dashboards.

/api/dashboards/<uid>/favorite

To make a dashboard a favorite you can make a POST request (no content type required) to a URL like this:

/api/dashboards/iMnYyBfSxmM/favorite

To remove a dashboard as a favorite you can make a DELETE request using the same URL as above.

The favorite status will appear as a boolean favorite field on the object (e.g. the dashboard) in the metadata response.

Subscriptions

A logged user can subscribe to certain types of objects. Currently subscribable objects are those of type Chart, EventChart, EventReport, Map, ReportTable and Visualization.

Note

The Chart and ReportTable objects are deprecated. Use Visualization instead.

To get the subscribers of an object (return an array of user IDs) you can make a GET request:

/api/<object-type>/<object-id>/subscribers

See example as follows:

/api/charts/DkPKc1EUmC2/subscribers

To check whether the current user is subscribed to an object (returns a boolean) you can perform a GET call:

/api/<object-type>/<object-id>/subscribed

See example as follows:

/api/charts/DkPKc1EUmC2/subscribed

To subscribe/de-subscribe to an object you perform a POST/DELETE request (no content type required):

/api/<object-type>/<object-id>/subscriber

File resources

File resources are objects used to represent and store binary content. The FileResource object itself contains the file meta-data (name, Content-Type, size, etc.) as well as a key allowing retrieval of the contents from a database-external file store. The FileResource object is stored in the database like any other but the content (file) is stored elsewhere and is retrievable using the contained reference (storageKey).

/api/fileResources

The contents of file resources are not directly accessible but are referenced from other objects (such as data values) to store binary content of virtually unlimited size.

To create a file resource that does not require a corresponding data value, POST to the endpoint /api/fileResources with a multipart upload:

curl "https://server/api/fileResources" -X POST
  -F "file=@/path/to/file/name-of-file.png"

To create both a file resource and a data value that references the file, POST to the /api/dataValues/file endpoint in DHIS 2.36 or later:

curl "https://server/api/dataValues/file?de=xPTAT98T2Jd
  &pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s" -X POST
  -F "file=@/path/to/file/name-of-file.png"

For the api/fileResources endpoint, the only form parameter required is file, which is the file to upload. For the api/dataValues/file endpoint, the parameters required are the same as for a post to api/dataValues, with the addition of file.

The filename and content-type should also be included in the request but will be replaced with defaults when not supplied.

On successfully creating a file resource the returned data will contain a response field which in turn contains the fileResource like this:

{
  "httpStatus": "Accepted",
  "httpStatusCode": 202,
  "status": "OK",
  "response": {
    "responseType": "FileResource",
    "fileResource": {
      "name": "name-of-file.png",
      "created": "2015-10-16T16:34:20.654+0000",
      "lastUpdated": "2015-10-16T16:34:20.667+0000",
      "externalAccess": false,
      "publicAccess": "--------",
      "user": { ... },
      "displayName": "name-of-file.png",
      "contentType": "image/png",
      "contentLength": 512571,
      "contentMd5": "4e1fc1c3f999e5aa3228d531e4adde58",
      "storageStatus": "PENDING",
      "id": "xm4JwRwke0i"
    }
  }
}

Note that the response is a 202 Accepted, indicating that the returned resource has been submitted for background processing (persisting to the external file store in this case). Also, note the storageStatus field which indicates whether the contents have been stored or not. At this point, the persistence to the external store is not yet finished (it is likely being uploaded to a cloud-based store somewhere) as seen by the PENDING status.

Even though the content has not been fully stored yet the file resource can now be used, for example as referenced content in a data value (see Working with file data values). If we need to check the updated storageStatus or otherwise retrieve the metadata of the file, the fileResources endpoint can be queried.

curl "https://server/api/fileResources/xm4JwRwke0i" -H "Accept: application/json"

This request will return the FileResource object as seen in the response of the above example.

File resource constraints

• File resources must be referenced (assigned) from another object in order to be persisted in the long term. A file resource which is created but not referenced by another object such as a data value is considered to be in staging. Any file resources which are in this state and are older than two hours will be marked for deletion and will eventually be purged from the system.

• The ID returned by the initial creation of the file resource is not retrievable from any other location unless the file resource has been referenced (in which the ID will be stored as the reference), so losing it will require the POST request to be repeated and a new object to be created. The orphaned file resource will be cleaned up automatically.

• File resource objects are immutable, meaning modification is not allowed and requires creating a completely new resource instead.

File resource blocklist

Certain types of files are blocked from being uploaded for security reasons.

The following content types are blocked.

The following file extensions are blocked.

Metadata versioning

This section explains the Metadata Versioning APIs available starting 2.24

• /api/metadata/version: This endpoint will return the current metadata version of the system on which it is invoked.

Get metadata version examples

Example: Get the current metadata version of this system

Request:

/api/metadata/version

Response:

{
    "name": "Version_4",
    "created": "2016-06-30T06:01:28.684+0000",
    "lastUpdated": "2016-06-30T06:01:28.685+0000",
    "externalAccess": false,
    "displayName": "Version_4",
    "type": "BEST_EFFORT",
    "hashCode": "848bf6edbaf4faeb7d1a1169445357b0",
    "id": "Ayz2AEMB6ry"
}

Example: Get the details of version with name "Version_2"

Request:

/api/metadata/version?versionName=Version_2

Response:

{
    "name": "Version_2",
    "created": "2016-06-30T05:59:33.238+0000",
    "lastUpdated": "2016-06-30T05:59:33.239+0000",
    "externalAccess": false,
    "displayName": "Version_2",
    "type": "BEST_EFFORT",
    "hashCode": "8050fb1a604e29d5566675c86d02d10b",
    "id": "SaNyhusVxBG"
}

• /api/metadata/version/history: This endpoint will return the list of all metadata versions of the system on which it is invoked.

Get the list of all metadata versions

Example: Get the list of all versions in this system

Request:

/api/metadata/version/history

Response:

{
    "metadataversions": [
        {
            "name": "Version_1",
            "type": "BEST_EFFORT",
            "created": "2016-06-30T05:54:41.139+0000",
            "id": "SjnhUp6r4hG",
            "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798"
        },
        {
            "name": "Version_2",
            "type": "BEST_EFFORT",
            "created": "2016-06-30T05:59:33.238+0000",
            "id": "SaNyhusVxBG",
            "hashCode": "8050fb1a604e29d5566675c86d02d10b"
        },
        {
            "name": "Version_3",
            "type": "BEST_EFFORT",
            "created": "2016-06-30T06:01:23.680+0000",
            "id": "FVkGzSjAAYg",
            "hashCode": "70b779ea448b0da23d8ae0bd59af6333"
        }
    ]
}

Example: Get the list of all versions in this system created after "Version_2"

Request:

/api/metadata/version/history?baseline=Version_2

Response:

{
    "metadataversions": [
        {
            "name": "Version_3",
            "type": "BEST_EFFORT",
            "created": "2016-06-30T06:01:23.680+0000",
            "id": "FVkGzSjAAYg",
            "hashCode": "70b779ea448b0da23d8ae0bd59af6333"
        },
        {
            "name": "Version_4",
            "type": "BEST_EFFORT",
            "created": "2016-06-30T06:01:28.684+0000",
            "id": "Ayz2AEMB6ry",
            "hashCode": "848bf6edbaf4faeb7d1a1169445357b0"
        }
    ]
}

• /api/metadata/version/create: This endpoint will create the metadata version for the version type as specified in the parameter.

Users can select the type of metadata which needs to be created. Metadata Version type governs how the importer should treat the given version. This type will be used while importing the metadata. There are two types of metadata.

• BEST_EFFORT: This type suggests that missing references can be ignored and the importer can continue importing the metadata (e.g. missing data elements on a data element group import).

• ATOMIC: This type ensures a strict type checking of the metadata references and the metadata import will fail if any of the references do not exist.

Note

It's recommended to have an ATOMIC type of versions to ensure that all systems (central and local) have the same metadata. Any missing reference is caught in the validation phase itself. Please see the importer details for a full explanation.

Create metadata version

Example: Create metadata version of type BEST_EFFORT

Request:

curl -X POST -u admin:district "https://play.dhis2.org/dev/api/metadata/version/create?type=BEST_EFFORT"

Response:

{
    "name": "Version_1",
    "created": "2016-06-30T05:54:41.139+0000",
    "lastUpdated": "2016-06-30T05:54:41.333+0000",
    "externalAccess": false,
    "publicAccess": "--------",
    "user": {
        "name": "John Traore",
        "created": "2013-04-18T17:15:08.407+0000",
        "lastUpdated": "2016-04-06T00:06:06.571+0000",
        "externalAccess": false,
        "displayName": "John Traore",
        "id": "xE7jOejl9FI"
    },
    "displayName": "Version_1",
    "type": "BEST_EFFORT",
    "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798",
    "id": "SjnhUp6r4hG"
}

• /api/metadata/version/{versionName}/data: This endpoint will download the actual metadata specific to the version name passed as path parameter.

• /api/metadata/version/{versionName}/data.gz: This endpoint will download the actual metadata specific to the version name passed as path parameter in a compressed format (gzipped).

Download version metadata

Example: Get the actual metadata for "Version 5"

Request:

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/version/Version_5/data"

Response:

{
    "date": "2016-06-30T06:10:23.120+0000",
    "dataElements": [
        {
            "code": "ANC 5th Visit",
            "created": "2016-06-30T06:10:09.870+0000",
            "lastUpdated": "2016-06-30T06:10:09.870+0000",
            "name": "ANC 5th Visit",
            "id": "sCuZKDsix7Y",
            "shortName": "ANC 5th Visit ",
            "aggregationType": "SUM",
            "domainType": "AGGREGATE",
            "zeroIsSignificant": false,
            "valueType": "NUMBER",
            "categoryCombo": {
                "id": "p0KPaWEg3cf"
            },
            "user": {
                "id": "xE7jOejl9FI"
            }
        }
    ]
}

Metadata Synchronization

This section explains the Metadata Synchronization API available starting 2.24

• /api/metadata/sync: This endpoint performs metadata sync of the version name passed in the query parameter by downloading and importing the specified version from the remote server as defined in the settings app.

• This API should be used with utmost care. Please note that there is an alternate way to achieve sync in a completely automated manner by leveraging the Metadata Sync Task from the "Data Administration" app. See Chapter 22, Section 22.17 of User Manual for more details regarding Metadata Sync Task.

• This sync API can alternatively be used to sync metadata for the versions which have failed from the metadata sync scheduler. Due to its dependence on the given metadata version number, care should be taken for the order in which this gets invoked. E.g. If this api is used to sync some higher version from the central instance, then the sync might fail as the metadata dependencies are not present in the local instance.

• Assume the local instance is at Version_12 and if this endpoint is used to sync Version_15 (of type BEST_EFFORT) from the central instance, the scheduler will start syncing metadata from Version_16. So the local instance will not have the metadata versions between Version_12 and Version_15. You need to manually sync the missing versions using these endpoints only.

Sync metadata version

Example: Sync Version_6 from central system to this system

Request:

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/sync?versionName=Version_6"

Metadata repository

DHIS2 provides a metadata repository containing metadata packages with various content. A metadata package is a DHIS2-compliant JSON document which describes a set of metadata objects.

To retrieve an index over available metadata packages you can issue a GET request to the metadataRepo resource:

GET /api/synchronization/metadataRepo

A metadata package entry contains information about the package and a URL to the relevant package. An index could look like this:

{
    "packages": [
        {
            "id": "sierre-leone-demo",
            "name": "Sierra Leone demo",
            "description": "Sierra Leone demo database",
            "version": "0.1",
            "href": "https://dhis2.org/metadata-repo/221/sierra-leone-demo/metadata.json"
        },
        {
            "id": "trainingland-org-units",
            "name": "Trainingland organisation units",
            "description": "Trainingland organisation units with four levels",
            "version": "0.1",
            "href": "https://dhis2.org/metadata-repo/221/trainingland-org-units/metadata.json"
        }
    ]
}

A client can follow the URLs and install a metadata package through a POST request with content type text/plain with the metadata package URL as the payload to the metadataPull resource:

POST /api/synchronization/metadataPull

An example curl command looks like this:

curl "localhost:8080/api/synchronization/metadataPull" -X POST
  -d "https://dhis2.org/metadata-repo/221/trainingland-org-units/metadata.json"
  -H "Content-Type:text/plain" -u admin:district

Metadata Gist API

The Metadata Gist API is a RESTful read-only JSON API to fetch and browse metadata. Items in this API contain the gist of the same item in the Metadata API.

The API is specifically designed to avoid:

• large response payloads because of the inclusion of partial nested object graphs
• resource intensive in memory processing of requests (e.g. in memory filtering or object graph traversal)
• n + 1 database queries as a result of object graph traversal while rendering the response

Comparison with Metadata API

The standard Metadata API is a flexible and powerful API built to serve any and every use case. The downside of this is that not all features and combinations can scale while keeping good performance in the presence of huge numbers of items. In particular lists with items where each item itself has a property which is a large collection of complex objects have proven problematic as they quickly reference a large part of the entire object graph.

The /gist API was added to provide a metadata API where scaling well is our first priority. The downside of this is that there are more distinct limits to what features are technically reasonable, which means not all features of the standard Metadata API exist for the Gist API.

The Gist API uses a divide and conquer strategy to avoid responses with large partial object graphs. Instead of including nested objects or lists it provides a /gist endpoint URI where this object or list can be viewed in isolation. The /gist API refers to nested data using URIs rather than including it. This means if a client is interested in this nested information more request are required but each of them is kept reasonable small and will scale well in context of huge number of potential items.

Known Differences:

• items never include fields with identifiable objects or list of such objects
• items by default do not include all available fields but a subset that depends on context and parameters
• lists cannot be used without pager (therefore there is no pager parameter)
• fields with collections are not paged using the pager-transformer but through a paged API endpoint for the particular collection property
• items in a list, a collection property size or boolean transformer result always considers object sharing (the set of considered items is always the set visible to the user)
• Gist offers member(<id>) and not-member(<id>) collection field transformers

Known Limitations:

• only persisted or synthetic fields (those based on persisted fields) can be included
• filters can only be applied to persisted fields
• orders can only be applied to persisted fields
• like-filters are always case-insensitive
• token filters are not available
• order is always case-sensitive
• pluck transformer limited to text properties
• fields which hold collections of simple (non-identifiable) items cannot always be included depending on how they are stored

Where possible to use the /gist API should be considered the preferable way of fetching metadata information.

Endpoints

The /gist API has 3 kinds of endpoints:

• /api/<object-type>/gist: paged list of all known and visible objects of the type (implicit auto=S)
• /api/<object-type>/<object-id>/gist: view single object by ID (implicit auto=L)
• /api/<object-type>/<object-id>/<field-name>/gist: paged list of all known and visible items in the collection of owner object's field (implicit auto=M; in case this is a simple field just the field value)

These endpoints correspond to the endpoints of the standard metadata API without the /gist suffix and share the majority of parameters and their options with that API.

Browsing Data

Since /gist API avoids deeply nested data structures in the response the details of referenced complex objects or list of objects is instead provided in form of a URI to the gist endpoint that only returns the complex object or list of objects. These URIs are provided by the apiEndpoints field of an item which is automatically added to an item when such references exist. The item property itself might contain a transformation result on the object or collection such as its size, emptiness, non-emptiness, id(s) or plucked property such as its name.

To manually browse data it can be handy to use the absoluteUrls=true parameter. Linkage between parts of the gist can now be followed directly in browsers that render JSON responses.

Parameters

All endpoints of the /gist API accept the same set of parameters. Parameters and their options that do not make sense in the endpoint context are ignored.

Overview

Parameters in alphabetical order:

• absoluteUrls: true (default) use relative paths in links, false use absolute URLs in links
• auto: XS,S,M,L,XL extent of fields selected by * field selector
• fields: comma separated list of fields to include (default is *)
• filter: comma separated list of query field filters (can be used more than once)
• headless: true skip wrapping result in a pager (ignores total), false (default) use a pager wrapper object around the result list
• inverse: true return items not in the list, false (default) return items in the list
• order: comma separated list of query order fields (can be used more than once)
• page: {1..n} page number
• pageSize: {1..1000} number of items on a page (default is 50)
• rootJunction: AND (default) or OR combination of filters
• total: true add total number of matches to the pager, false (default) skip counting total number of matches
• translate: true (default) translate all translatable properties, false skip translation of translatable properties (no effect on synthetic display names)

The absoluteUrls Parameter

By default, URIs in apiEndpoints, href and the pager'sprev and next members are relative, starting with /<object-type>/ path.

The URIs can be changed to absolute URLs using the absoluteUrls parameter.

For example, /api/users/rWLrZL8rP3K/gist?fields=id,href returns:

{
    "id": "rWLrZL8rP3K",
    "href": "/users/rWLrZL8rP3K/gist"
}

whereas /api/users/rWLrZL8rP3K/gist?fields=id,href&absoluteUrls=true returns:

{
    "id": "rWLrZL8rP3K",
    "href": "http://localhost:8080/api/users/rWLrZL8rP3K/gist?absoluteUrls=true"
}

As the example shows the absoluteUrls parameter is also forwarded or carried over to the included URLs so allowing to browse the responses by following the provided URLs.

The auto Parameter

Each endpoint implicitly sets a default for the extent of fields matched by the */:all fields selector:

• /api/<object-type>/gist: implies auto=S
• /api/<object-type>/<object-id>/gist: implies auto=L
• /api/<object-type>/<object-id>/<field-name>/gist: implies auto=M

The auto parameter is used to manually override the default to make list items include more or less fields. This setting again acts as a default which can be further overridden on a per field basis using an explicit transformation.

Possible options for auto are ("t-shirt sizes"):

• XS: includes only IDs and textual properties
• S: excludes complex (object) properties, collection are only linked (not counted)
• M: complex included as reference URL, collections as count and reference URL
• L: like M but collections included as list of IDs (OBS! unbound in size)
• XL: like L but collections included as ID objects: { "id": <id> }

For example, /api/users/gist would list items with fields id, surname, firstName, phoneNumber, email, lastUpdated whereas /api/users/gist?auto=XS only lists id, surname, firstName, phoneNumber, email. Using /api/users/gist?auto=L would also include organisationUnits, dataViewOrganisationUnits, teiSearchOrganisationUnits and userGroups each with the list of IDs of the members in the lists/sets.

The fields Parameter

Specifies the list of fields to include for each list item.

Fields are included in the result JSON objects for an item in the provided order. A preset in the list of fields is expanded to the fields it contains at the position in the fields list it appears. Fields within the preset are ordered from simple to complex.

If no fields parameter is provided fields=* is assumed. Note that the fields of the * preset also depend on the auto parameter

To remove a field use either !<name> or -<name> in the list of fields. For example to remove the userGroups from a user, use:

/api/users/gist?fields=*,!userGroups

The same principle can also be used to specify the transformer to use for a field. For example, to include the IDs of the user's user groups use:

/api/users/gist?fields=*,userGroups::ids

When using field presets like this it is important to remember that the last declaration of each fields wins over prior ones. In the opposite order

/api/users/gist?fields=userGroups::ids,*

the userGroups would not be shown with IDs since * expands among other fields to userGroups::none which replaces the explicit userGroups::ids.

The fields parameter does allow listing fields of nested objects as long as there is a 1:1 relation. For example to add userCredentials with id and name of a user use:

/api/users/gist?fields=*,userCredentials[id,username]

This creates items of the form:

{
  ...
  "userCredentials": {
    "id": "Z9oOHPi3FHB",
    "username": "guest"
  }
}

A way to partly overcome the 1:1 limitation and to include fields of nested collection is the pluck transformer. It allows for example to include all names of a user's userGroups by:

/api/users/gist?fields=*,userGroups::pluck(name)

This lists the userGroups as:

{
    "userGroups": [
        "_PROGRAM_Inpatient program",
        "_PROGRAM_TB program",
        "_DATASET_Superuser",
        "_PROGRAM_Superuser",
        "_DATASET_Data entry clerk",
        "_DATASET_M and E Officer"
    ]
}

When requesting a single field, like /api/users/gist?fields=surname the response is a (still paged) list of simple values:

{
  "pager": {
    "page": 1,
    "pageSize": 50
  },
  "users": [
    "Kamara",
    "Wakiki",
    "Nana",
    "Malai",
    ...
  ]
}

When requesting a single field of a specific owner object which has a simple (non collection) value, like for example /api/users/rWLrZL8rP3K/gist?fields=surname the response only include the plain JSON value:

"Wakiki"

Further details on field presets can be found in section Fields.

The filter Parameter

To filter the list of returned items add one or more filter parameters.

Multiple filters can either be specified as comma seperated list of a single filter parameter or as multiple filter parameters each with a single filter.

There are two types of filters:

• unary: <field>:<operator>
• binary: <field>:<operator>:<value>

A field must be a persisted field of the listed item type or field of a directly referenced object (1:1 relation).

Available unary operators are:

• null: field is null (undefined)
• !null: field is not null (defined)
• empty: field is a empty collection
• !empty: field is a non-empty collection

Available binary operators are:

• eq: field equals value
• !eq, neq, ne: field is not equal value
• lt: field is less than value
• le, lte: field is less than or equal to value
• gt: field is greater than value
• ge, gte: field is greater than or equal to value
• in: field is a collection and value is an item contained in the collection
• !in: field is a collection and value is an item not contained in the collection

If the <value> of an in or !in filter is a list it is given in the form [value1,value2,...], for example: userGroups:in:[fbfJHSPpUQD,cYeuwXTCPkU].

Any >, >=, < <=, == or != comparison applied to a collection field with a numeric value will compare the size of the collection to the value, for example: userGroups:gt:0.

Available binary pattern matching operators are:

• like, ilike: field contains <value> or field matches pattern <value> (when wildcards * or ? in value)
• !like, !ilike: field does not contain <value> or field does not match pattern <value> (when wildcards * or ? in value)
• $like, $ilike, startsWith: field starts with <value>
• !$like, !$ilike: field does not start with <value>
• like$, ilike$, endsWith: field ends with <value>
• !like$, !ilike$: field does not end with <value>

The like and !like operators can be used by either providing a search term in which case a match is any value where the term occurs anywhere or they can be used by providing the search pattern using * as any number of characters and ? any single character.

Some operators have multiple aliases to be backwards compatible with the standard metadata API. For the gist API any like is always case-insensitive.

For example, to only list organisations on 2^nd level use

/api/organisationUnits/gist?filter=level:eq:2

Similarly, when listing the children of a particular organisation unit the collection can be filtered. To only list those children that are connected to a program one would use:

/api/organisationUnits/rZxk3S0qN63/children/gist?filter=programs:gt:0

The headless Parameter

Endpoints returning a list by default wrap the items with an envelope containing the pager and the list, which is named according to the type of object listed.

For example /api/organisationUnits/gist returns:

{
  "pager": {
    "page": 1,
    "pageSize": 50,
    "nextPage": "/organisationUnits/gist?page=2"
  },
  "organisationUnits": [
    ...
  ]
}

With headless=true the response to /api/organisationUnits/gist?headless=true is just the [...] list part in above example.

The inverse Parameter

The inverse can be used in context of a collection field gist of the form /api/<object-type>/<object-id>/<field-name>/gist to not list all items that are contained in the member collection but all items that are not contained in the member collection.

For example, while

/api/organisationUnits/rZxk3S0qN63/children/gist

would list all organisation units that are children of rZxk3S0qN63 the inverse

/api/organisationUnits/rZxk3S0qN63/children/gist?inverse=true

would list all organisation units that are not children of rZxk3S0qN63. This would e.g. be used to compose a list of all units that can be made a child of a particular unit.

Filters and orders do apply normally, meaning they filter or order the items not contained in the member collection.

The order Parameter

To sort the list of items one or more order expressions can be given.

An order expression is either just a field name of a persisted field or a field name followed by :asc (ascending order - the default) or :desc (descending order).

For example, to sort organisation units alphabetically by name use:

/api/organisationUnits/gist?order=name

Reverse alphabetical order would use:

/api/organisationUnits/gist?order=name:desc

To sort organisation units first by level, then by name use:

/api/organisationUnits/gist?order=level,name

This would start with root(s) at level 1. To start with the leaf units use:

/api/organisationUnits/gist?order=level:desc,name

If no order is specified the result list will have a stable order based on internal data organisation.

The page Parameter

Refers to the viewed page in paged list starting with 1 for the first page.

If no page parameter is present this is equal to page=1.

The page is always in relation to the pageSize. If a page is given beyond the number of existing matches an empty item list is returned.

The pageSize Parameter

Refers to the number of items on a page. Maximum is 1000 items.

If no pageSize parameter is present this is equal to pageSize=50.

The rootJunction Parameter

The rootJunction parameter can be used to explicitly set the logic junction used between filters. Possible are:

• AND: all filters have to match an entry for it to be included in the results
• OR: any of the filters matches an entry for it to be included in the results

Default is AND.

The total Parameter

By default, a gist query will not count the total number of matches should those exceed the pageSize limit. Instead, we opt-in to the additional costs the total count implicates.

When not counting the total matches (total=false) the response pager will assume that there is a next page in case pageSize items were found. This could however turn out to be false when browsing to the page. Also, the total field stating the number of total matches is not included in the pager.

For example, /api/organisationUnits/gist returns a pager:

{
    "pager": {
        "page": 1,
        "pageSize": 50,
        "nextPage": "/organisationUnits/gist?page=2"
    }
}

When counting the total matches (total=true) the response pager will contain the total field with the actual number of total matches at the cost of an additional database operation.

The response to /api/organisationUnits/gist?total=true now returns this pager:

{
    "pager": {
        "page": 1,
        "pageSize": 50,
        "total": 1332,
        "nextPage": "/organisationUnits/gist?total=true&page=2",
        "pageCount": 27
    }
}

The translate Parameter

Fields like name or shortName can be translated (internationalised).

By default, any translatable field that has a translation is returned translated given that the user requesting the gist has an interface language configured.

To return the plain non-translated field use translate=false.

For example, /api/organisationUnits/gist returns items like this:

{
  "name": "A translated name",
  ...
}

Whereas /api/organisationUnits/gist?translate=false would return items like:

{
  "name"
  "Plain field name",
  ...
}

Note that synthetic fields displayName and displayShortName are always returning the translated value independent of the translate parameter.

Fields

The fields included by default (without fields parameter) correspond to fields=*. This means the list of fields shown depends on object type, endpoint context as well as the auto parameter.

Note that the /gist API always excludes certain fields that usually are of no interest to clients, like for example the translations or sharing fields. These can be added explicitly.

When not explicitly provided by name in the fields parameters the list of fields is computed from a preset. A preset can be used in the list of fields like a field name. It expands to zero, one or many fields depending on the object type, used endpoint and selector.

Field Presets

• * / :all: default fields depend on the context and auto parameter
• :identifiable: all persisted fields of the IdentifiableObject interface
• :owner: all persisted fields where the listed type is the owner
• :nameable: all persisted fields of the NameableObject interface
• :persisted: literally all persisted fields

Field Transformers

A transformer or transformation can be applied to a field by appending any of the indicators ::, ~ or @ followed by the transformer expression.

Available transformer expressions are:

• rename(<name>): renames the field in the response to <name>
• size => number: number of items in the collection field
• isEmpty => boolean: emptiness of a collection field
• isNotEmpty => boolean: non-emptiness of a collection field
• ids => (array of) string: ID of an object or IDs of collection items
• id-objects => array of { "id": <id> }: IDs of collection items as object
• member(<id>) => boolean: has member with <id> for collection field
• not-member(<id>) => boolean: not has member with <id> for collection field
• pluck(<field>) => (array of) string: extract single text property of the object or of each collection item

A field can receive both the rename transformer and one of the other transformers, for example:

/api/organisationUnits/gist?fields=*,children::size~rename(child-count)

The returned items now no longer have a chilren member but a child-count member instead. Note that rename also affects the member name of the URI reference given in apiEndpoints.

Synthetic Fields

The /gist API is tightly coupled to properties that exist the database. This means properties that aren't stored in the database usually aren't available. The exception to this are the "synthetic" properties which are dynamically computed on the basis of one or more database stored properties.

Synthetic properties are available for all endpoints where the persisted properties needed to compute the synthetic property exist.

Except for the apiEndpoints property which is automatically added when needed all other synthetic properties are not included by default and have to be requested explicitly in the list of fields.

Overview

Synthetic fields in alphabetical order:

• apiEndpoints: contains links to browse nested complex objects or collections
• href: link to the list item itself (single item view)
• displayName: translated name (always translated)
• displayShortName: translated displayName (always translated)

The href Field

Each item in a /gist response can link to itself. This link is given in the href property.

To add the href field use (for example):

    /api/<object-type>/gist?fields=*,href

The displayName and displayShortName Field

By definition the displayName is the translated name and the displayShortName is the translated shortName.

To add displayName or displayShortName add it to the list use (for example):

    /api/<object-type>/gist?fields=*,displayName
    /api/<object-type>/gist?fields=*,displayShortName

Note that by default all translatable properties like name and shortName would also be translated. When translate=false is used to disable this displayName and displayShortName stay translated.

The apiEndpoints Field

This property provides the links to further browse complex objects or list of items that are included in the /gist response in form of a transformed simple value like an item count.

The apiEndpoints object will have a member of the same name for every member in the item that was transformed to a simple value.

For example, /api/users/gist?fields=id,userGroups::size,organisationUnits::size returns items in the form:

{
    "id": "rWLrZL8rP3K",
    "userGroups": 0,
    "organisationUnits": 1,
    "apiEndpoints": {
        "organisationUnits": "/users/rWLrZL8rP3K/organisationUnits/gist",
        "userGroups": "/users/rWLrZL8rP3K/userGroups/gist"
    }
}

The list of userGroups and organisationUnits are included as their size. Each has a corresponding member in apiEndpoints with the path to browse the list.

The paths can be changed to URLs by using the absoluteUrls parameter.

/api/users/gist?fields=id,userGroups::size,organisationUnits::size&absoluteUrls=true

returns items in the form:

{
    "id": "rWLrZL8rP3K",
    "userGroups": 0,
    "organisationUnits": 1,
    "apiEndpoints": {
        "organisationUnits": "http://{host}/api/users/rWLrZL8rP3K/organisationUnits/gist?absoluteUrls=true",
        "userGroups": "http://{host}/api/users/rWLrZL8rP3K/userGroups/gist?absoluteUrls=true"
    }
}

Examples

A few examples starting from simple listings moving to tips on very specific use cases.

It is preferable to always supply an explicit list of fields so this section will do so.

List organisation units with id and name:

/api/organisationUnits/gist?fields=id,name

List organisation units with id and name and total count:

/api/organisationUnits/gist?fields=id,name&total=true

List users with id and username:

/api/users/gist?fields=id,userCredentials.username

List users with id, username and last login date:

/api/users/gist?fields=id,userCredentials[username,lastLogin]

List only organisation units on second level with id, name and level:

/api/organisationUnits/gist?fields=id,name,level&filter=level:eq:2

List only organisation units that have more than 1 child with id, name and number of children:

/api/organisationUnits/gist?fields=id,name,children::size&filter=children:gt:1

List only organisation units that are not yet a children of another unit zFDYIgyGmXG:

/api/organisationUnits/zFDYIgyGmXG/children/gist?fields=id,name&inverse=true

List users and flag whether they are a member of a specific user group NTC8GjJ7p8P and name that field is-member in the response:

/api/users/gist?fields=id,userCredentials.username,userGroups::member(NTC8GjJ7p8P)~rename(is-member)

List links to all users in pages of 10 items:

/api/users/gist?fields=href&absoluteUrls&pageSize=10

Data

Data values

This section is about sending and reading data values.

/api/33/dataValueSets

Sending data values

A common use-case for system integration is the need to send a set of data values from a third-party system into DHIS. In this example, we will use the DHIS2 demo on http://play.dhis2.org/demo as basis. We assume that we have collected case-based data using a simple software client running on mobile phones for the Mortality <5 years data set in the community of Ngelehun CHC (in Badjia chiefdom, Bo district) for the month of January 2014. We have now aggregated our data into a statistical report and want to send that data to the DHIS2 instance. The base URL to the demo API is http://play.dhis2.org/demo/api. The following links are relative to the base URL.

The resource which is most appropriate for our purpose of sending data values is the /api/dataValueSets resource. A data value set represents a set of data values which have a relationship, usually from being captured off the same data entry form. The format looks like this:

<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="dataSetID"
  completeDate="date" period="period" orgUnit="orgUnitID" attributeOptionCombo="aocID">
  <dataValue dataElement="dataElementID"
    categoryOptionCombo="cocID" value="1" comment="comment1"/>
  <dataValue dataElement="dataElementID"
    categoryOptionCombo="cocID" value="2" comment="comment2"/>
  <dataValue dataElement="dataElementID"
    categoryOptionCombo="cocID" value="3" comment="comment3"/>
</dataValueSet>

JSON is supported in this format:

{
    "dataSet": "dataSetID",
    "completeDate": "date",
    "period": "period",
    "orgUnit": "orgUnitID",
    "attributeOptionCombo": "aocID",
    "dataValues": [
        {
            "dataElement": "dataElementID",
            "categoryOptionCombo": "cocID",
            "value": "1",
            "comment": "comment1"
        },
        {
            "dataElement": "dataElementID",
            "categoryOptionCombo": "cocID",
            "value": "2",
            "comment": "comment2"
        },
        {
            "dataElement": "dataElementID",
            "categoryOptionCombo": "cocID",
            "value": "3",
            "comment": "comment3"
        }
    ]
}

CSV is supported in this format:

"dataelement","period","orgunit","catoptcombo","attroptcombo","value","strby","lstupd","cmt"
"dataElementID","period","orgUnitID","cocID","aocID","1","username","2015-04-01","comment1"
"dataElementID","period","orgUnitID","cocID","aocID","2","username","2015-04-01","comment2"
"dataElementID","period","orgUnitID","cocID","aocID","3","username","2015-04-01","comment3"

Note

Please refer to the date and period section above for time formats.

From the example, we can see that we need to identify the period, the data set, the org unit (facility) and the data elements for which to report.

To obtain the identifier for the data set we make a request to the /api/dataSets resource. From there we find and follow the link to the Mortality < 5 years data set which leads us to /api/dataSets/pBOMPrpg1QX. The resource representation for the Mortality < 5 years data set conveniently advertises links to the data elements which are members of it. From here we can follow these links and obtain the identifiers of the data elements. For brevity we will only report on three data elements: Measles with id f7n9E0hX8qk, Dysentery with id Ix2HsbDMLea and Cholera with id eY5ehpbEsB7.

What remains is to get hold of the identifier of the organisation unit. The dataSet representation conveniently provides a link to organisation units which report on it so we search for Ngelehun CHC and follow the link to the HTML representation at /api/organisationUnits/DiszpKrYNg8, which tells us that the identifier of this org unit is DiszpKrYNg8.

From our case-based data, we assume that we have 12 cases of measles, 14 cases of dysentery and 16 cases of cholera. We have now gathered enough information to be able to put together the XML data value set message:

<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="pBOMPrpg1QX"
  completeDate="2014-02-03" period="201401" orgUnit="DiszpKrYNg8">
  <dataValue dataElement="f7n9E0hX8qk" value="12"/>
  <dataValue dataElement="Ix2HsbDMLea" value="14"/>
  <dataValue dataElement="eY5ehpbEsB7" value="16"/>
</dataValueSet>

In JSON format:

{
    "dataSet": "pBOMPrpg1QX",
    "completeDate": "2014-02-03",
    "period": "201401",
    "orgUnit": "DiszpKrYNg8",
    "dataValues": [
        {
            "dataElement": "f7n9E0hX8qk",
            "value": "1"
        },
        {
            "dataElement": "Ix2HsbDMLea",
            "value": "2"
        },
        {
            "dataElement": "eY5ehpbEsB7",
            "value": "3"
        }
    ]
}

To perform functional testing we will use the curl tool which provides an easy way of transferring data using HTTP. First, we save the data value set XML content in a file called datavalueset.xml. From the directory where this file resides we invoke the following from the command line:

curl -d @datavalueset.xml "https://play.dhis2.org/demo/api/33/dataValueSets"
  -H "Content-Type:application/xml" -u admin:district

For sending JSON content you must set the content-type header accordingly:

curl -d @datavalueset.json "https://play.dhis2.org/demo/api/33/dataValueSets"
  -H "Content-Type:application/json" -u admin:district

The command will dispatch a request to the demo Web API, set application/xml as the content-type and authenticate using admin/district as username/password. If all goes well this will return a 200 OK HTTP status code. You can verify that the data has been received by opening the data entry module in DHIS2 and select the org unit, data set and period used in this example.

The API follows normal semantics for error handling and HTTP status codes. If you supply an invalid username or password, 401 Unauthorized is returned. If you supply a content-type other than application/xml, 415 Unsupported Media Type is returned. If the XML content is invalid according to the DXF namespace, 400 Bad Request is returned. If you provide an invalid identifier in the XML content, 409 Conflict is returned together with a descriptive message.

Sending bulks of data values

The previous example showed us how to send a set of related data values sharing the same period and organisation unit. This example will show us how to send large bulks of data values which don't necessarily are logically related.

Again we will interact with the /api/dataValueSets resource. This time we will not specify the dataSet and completeDate attributes. Also, we will specify the period and orgUnit attributes on the individual data value elements instead of on the outer data value set element. This will enable us to send data values for various periods and organisation units:

<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0">
  <dataValue dataElement="f7n9E0hX8qk"
    period="201401" orgUnit="DiszpKrYNg8" value="12"/>
  <dataValue dataElement="f7n9E0hX8qk"
    period="201401" orgUnit="FNnj3jKGS7i" value="14"/>
  <dataValue dataElement="f7n9E0hX8qk"
    period="201402" orgUnit="DiszpKrYNg8" value="16"/>
  <dataValue dataElement="f7n9E0hX8qk"
    period="201402" orgUnit="Jkhdsf8sdf4" value="18"/>
</dataValueSet>

In JSON format:

{
    "dataValues": [
        {
            "dataElement": "f7n9E0hX8qk",
            "period": "201401",
            "orgUnit": "DiszpKrYNg8",
            "value": "12"
        },
        {
            "dataElement": "f7n9E0hX8qk",
            "period": "201401",
            "orgUnit": "FNnj3jKGS7i",
            "value": "14"
        },
        {
            "dataElement": "f7n9E0hX8qk",
            "period": "201402",
            "orgUnit": "DiszpKrYNg8",
            "value": "16"
        },
        {
            "dataElement": "f7n9E0hX8qk",
            "period": "201402",
            "orgUnit": "Jkhdsf8sdf4",
            "value": "18"
        }
    ]
}

In CSV format:

"dataelement","period","orgunit","categoryoptioncombo","attributeoptioncombo","value"
"f7n9E0hX8qk","201401","DiszpKrYNg8","bRowv6yZOF2","bRowv6yZOF2","1"
"Ix2HsbDMLea","201401","DiszpKrYNg8","bRowv6yZOF2","bRowv6yZOF2","2"
"eY5ehpbEsB7","201401","DiszpKrYNg8","bRowv6yZOF2","bRowv6yZOF2","3"

We test by using curl to send the data values in XML format:

curl -d @datavalueset.xml "https://play.dhis2.org/demo/api/33/dataValueSets"
  -H "Content-Type:application/xml" -u admin:district

Note that when using CSV format you must use the binary data option to preserve the line-breaks in the CSV file:

curl --data-binary @datavalueset.csv "https://play.dhis2.org/demo/24/api/dataValueSets"
  -H "Content-Type:application/csv" -u admin:district

The data value set resource provides an XML response which is useful when you want to verify the impact your request had. The first time we send the data value set request above the server will respond with the following import summary:

<importSummary>
  <dataValueCount imported="2" updated="1" ignored="1"/>
  <dataSetComplete>false</dataSetComplete>
</importSummary>

This message tells us that 3 data values were imported, 1 data value was updated while zero data values were ignored. The single update comes as a result of us sending that data value in the previous example. A data value will be ignored if it references a non-existing data element, period, org unit or data set. In our case, this single ignored value was caused by the last data value having an invalid reference to org unit. The data set complete element will display the date of which the data value set was completed, or false if no data element attribute was supplied.

Import parameters

The import process can be customized using a set of import parameters: