Day1-DHIS2 Web API

MOdule-2.1 What is API and Why DHIS2 Web API

“What is an API?” as “a way for one software component
to access another for function and/or data sharing through a well-defined agreement”.
Interface for computer systems to interact
REST architecture style
Resources
HTTP and headers
JSON and XML payloads
Exposes DHIS 2 data model and most services

DHIS2 Web API and Resources

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 DHIS 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.

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 a Accept: application/pdf header or append .pdf or ?format=pdf to your request URL.

Interactions with the API requires 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.

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 reportTableresource through the embedded links using your preferred representation format.

API and Real Life Example:

Bangladesh scenario for the communication between:

DHIS2 and HRIS
DHIS2 and DGHS Webportal
eLMIS and DHIS2
eTB and DHIS2
EQUEST and DHIS2
eMIS/RHIS and DHIS2

Example of DHIS2 API:

POST /api/constants
PUT /api/constants/h7JkTWGh62P
GET /api/dataValueSets?dataSet=pBOMPrpg1QX&period=201401
GET /api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2014Q1

Why DHIS2 Web API

Allows external systems and apps to talk to DHIS 2
Uniform API for all clients
Android apps
Web apps
Connectors / integrations
Web portals

Module-2.2 HTTP and REST Principle

HTTP
- Methods: GET, POST, PUT, PATCH, DELETE
- Headers, key: value pairs
Accept header, what can your client accept (json, xml, etc)
- Accept: application/json
- Accept: application/xml
Content-Type header, what is your client sending (json, xml, etc)
- Content-Type: application/json
- Content-Type: application/xml
- HTTP based protocol, Stateless, Client to Server, Link (url) based

Say for, you have a table with list of users: 
GET: api/users/IE1zznX91pR


POST: If you POST this document to /users, as you suggest, then you might get back an entity such as
## /users
{
  "id": "IE1zznX91pR",
  "firstName": "Julhas",
  "surname": "Sujan",
  "email": "julhaspustcse@gmail.com",
  "userCredentials": {
      "userInfo": { "id": "IE1zznX91pR" },
    "username": "julhas999",
    "password": "DHIS2@9876",
    "userRoles": [ {
      "id": "mo3t1mDUOmy"
    } ]
  }
}
If you want to modify this entity later, you choose between PUT and PATCH. A PUT might look like this:
PUT /users/IE1zznX91pR
{
    "firstName": "Julhas",
    "surname": "Sujan",
    "username": "julhas999",
    "email": "julhas08@gmail.com"     
}

You can accomplish the same using PATCH. That might look like this:
PATCH /users/Xbj9AWLGEse
{
    "email": "julhas990@gmail.com"     
}
The PUT included all of the parameters on this user, but PATCH only included the one that was being modified

DHIS2 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/26/me 

Example # Open your Postman and Add the below URL:
 
Method: GET 
URL: https://play.dhis2.org/2.29/api/me
Authorization type: Basic Auth
Username: admin
Pass: district

Output: 
{
    "lastUpdated": "2018-06-02T13:07:21.059",
    "id": "xE7jOejl9FI",
    "created": "2013-04-18T17:15:08.407",
    "name": "John Traore",
    "birthday": "1971-04-08T00:00:00.000",
    "education": "Master of super using",
    "gender": "gender_male",
    "displayName": "John Traore",
    "jobTitle": "Super user",
    "externalAccess": false,
    "surname": "Traore",
    "employer": "DHIS",
    "introduction": "I am the super user of DHIS 2",
    "email": "someone@dhis2.org",
    "languages": "English",
...............
}

Basic authentication

Should be used over SSL only!
Credentials is sent in request header Authorization
Authorization: Basic base64encode(username:password)

In NodeJS you can use:

"Basic " + new Buffer( username + ":" + password ).toString( "base64" );

OAuth2

DHIS2 supports the OAuth2 authentication protocol. OAuth2 is an open standard for authorization which it 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. DHIS 2 does not support fine-grained OAuth2 roles but rather provides applications access based on user roles of the DHIS2 user.

Example # Get all auth tokens:
Api: https://play.dhis2.org/2.29/api/oAuth2Clients
Result: 
{"pager":{"page":1,"pageCount":1,"total":1,"pageSize":50},"oAuth2Clients":[{"id":"eaHDXRowyXr","displayName":"OAuth2 Demo Client"}]}

Example # Create new token: 
UIL: https://play.dhis2.org/2.29/api/oAuth2Clients
Method: POST
JSON Payload:  
{
   "name" : "OAuth2 Demo Client",
   "cid" : "demo",
   "secret" : "1e6db50c-0fee-11e5-98d0-3c15c2c6caf6",
   "grantTypes" : [
      "password",
      "refresh_token",
      "authorization_code"
   ],
   "redirectUris" : [
      "http://www.example.org"
   ]
}
From Terminal: 
SERVER="https://play.dhis2.org/dev" 
curl -X POST -H "Content-Type: application/json" -d @client.json -u admin:district $SERVER/api/oAuth2Clients

Output: 
{"httpStatus":"Created","httpStatusCode":201,"status":"OK","response":{"responseType":"ObjectReport","klass":"org.hisp.dhis.security.oauth2.OAuth2Client","uid":"eaHDXRowyXr"}}

How to create OAuth2 in DHIS2: Apps >> System Settings >> OAuth2 Clients

How to access OAuth2 from your application:

Example # How to get OAuth2 detail from Postman: API: https://play.dhis2.org/2.29/api/oAuth2Clients Method: GET Authorization: OAuth2.0 Access New Tocken: Callback: https://www.getpostman.com/oauth2/callback Token Name: Any name or matched with provided name Auth URL: https://play.dhis2.org/2.29/api/oAuth2Clients.json?fields=:all Access Token URL: 1e6db50c-0fee-11e5-98d0-3c15c2c6caf6 Client ID: admin Client Secrete: district Grant Type: Authorization Code Result:

{ "pager": { "page": 1, "pageCount": 1, "total": 1, "pageSize": 50 }, "oAuth2Clients": [{ "created": "2018-06-02T15:04:50.193", "lastUpdated": "2018-06-02T15:04:50.193", "name": "OAuth2 Demo Client", "href": "https://play.dhis2.org/2.29/api/oAuth2Clients/eaHDXRowyXr", "id": "eaHDXRowyXr", "displayName": "OAuth2 Demo Client", "secret": "1e6db50c-0fee-11e5-98d0-3c15c2c6caf6", "externalAccess": false, "favorite": false, "cid": "demo", "lastUpdatedBy": { "id": "xE7jOejl9FI" }, "access": { "read": true, "update": true, "externalize": false, "delete": true, "write": true, "manage": true }, "favorites": [], "userGroupAccesses": [], "attributeValues": [], "redirectUris": ["http://www.example.org"], "grantTypes": ["password", "refresh_token", "authorization_code"], "translations": [], "userAccesses": [] }] }

Api Endpoint Overview

Generally speaking, all types in DHIS2 are represented by an endpoint in the web-api:

○ Data Element: /api/dataElements

○ Data Element Groups: /api/dataElementGroups

○ Data Element Group Sets: /api/dataElementGroupSets

○ Organisation Units: /api/organisationUnits

○ Organisation Unit Levels: /api/organisationUnitLevels

○ Organisation Unit Groups: /api/organisationUnitGroups

○ Indicators: /api/indicators

○ Dashboard: /api/dashboards

○ Data Entry Forms: /api/dataEntryForms

○ Maps: /api/maps

○ Reports: /api/reports

○ Attributes: /api/attributes

○ Categories: /api/categories

○ Users: /api/users

○ User Groups: /api/userGroups

○ Sql Views: /api/sqlViews

○ O Auth2 Clients: /api/oAuth2Clients

○ Tracked Entity Types: /api/trackedEntityTypes

Most endpoints uses standard REST principles, and you can use GET to get data, PUT to update, POST to create, and DELETE to delete a resource

Example

How to get Data Elements with all fields?

Get Data Elements: http://103.247.238.86:8081/dhis28/api/dataElements.json?paging=true&fields=:all
"dataElements": [
    {
      "lastUpdated": "2017-06-20T13:18:34.277",
      "id": "Iyj1fHxdrYu",
      "href": "http://103.247.238.86:8081/dhis28/api/dataElements/Iyj1fHxdrYu",
      "created": "2017-06-06T12:25:54.079",
      "name": "10. si No of Cases Settled in Mobile Court",
      "shortName": "No of Cases Settled in Mobile Court",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "displayName": "10. si No of Cases Settled in Mobile Court",
      "publicAccess": "rw------",
      "displayShortName": "No of Cases Settled in Mobile Court",
      "externalAccess": false,
      "valueType": "NUMBER",
      "formName": "No of Cases Settled in Mobile Court",
      "dimensionItem": "Iyj1fHxdrYu",
      "displayFormName": "No of Cases Settled in Mobile Court",
      "zeroIsSignificant": false,
      "optionSetValue": false,
      "dimensionItemType": "DATA_ELEMENT",
      "access": {
        "read": true,
        "update": true,
        "externalize": true,
        "delete": true,
        "write": true,
        "manage": true
      },
      "categoryCombo": {
        "id": "VqkJtcTQb8E"
      },
      "user": {
        "id": "jYWagOOr1U6"
      },
      "dataSetElements": [
        {
          "categoryCombo": {
            "id": "VqkJtcTQb8E"
          },
          "dataElement": {
            "id": "Iyj1fHxdrYu"
          },
          "dataSet": {
            "id": "nfJdwviFfyB"
          }
        }
      ],
      "translations": [
        
      ],
      "userGroupAccesses": [
        
      ],
      "dataElementGroups": [
        {
          "id": "SYUXpi4JMr4"
        }
      ],
      "attributeValues": [
        
      ],
      "userAccesses": [
        
      ],
      "legendSets": [
        
      ],
      "aggregationLevels": [
        
      ]
    }
}

Create New Element: 
http://103.247.238.86:8081/dhis28/api/dataElements
JSON Payload: {
      "id": "IQW1OB11T7j",
      "created": "2018-04-15T19:26:32.716",
      "name": "Test DE for APP",
      "shortName": "Test DE for APP",
      "aggregationType": "AVERAGE_SUM_ORG_UNIT",
      "domainType": "AGGREGATE",
      "displayName": "Test DE for APP",
      "displayShortName": "Test DE for APP",
      "externalAccess": false,
      "valueType": "INTEGER_ZERO_OR_POSITIVE",
      "displayDescription": "Test DE for APP",
      "dimensionItem": "IQW1OBDMT7j",
      "zeroIsSignificant": false,
      "optionSetValue": false,
      "dimensionItemType": "DATA_ELEMENT",
      "access": {
        "read": true,
        "update": true,
        "externalize": true,
        "delete": true,
        "write": true,
        "manage": true
      }
}

Response: 
{
    "httpStatus": "Created",
    "httpStatusCode": 201,
    "status": "OK",
    "response": {
        "responseType": "ObjectReport",
        "uid": "IQW1OB11T7j",
        "klass": "org.hisp.dhis.dataelement.DataElement"
    }
}

Get the created element: 
http://103.247.238.86:8081/dhis28/api/dataElements.json?filter=id:eq:IQW1OB11T7j&fields=:all

Update the element: 
http://103.247.238.86:8081/dhis28/api/dataElements/IQW1OB11T7j
JSON Payload: 
{
      "name": "Test DE for APP-Updated",
      "shortName": "Test DE for APP-Updated",
      "aggregationType": "AVERAGE_SUM_ORG_UNIT",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
}

Delete Data Element:
{
      "id": "IQW1OB22T7j",
      "name": "Test DE for APP-22",
      "shortName": "Test DE for APP-22",
      "aggregationType": "AVERAGE_SUM_ORG_UNIT",
      "domainType": "AGGREGATE",
      "displayName": "Test DE for APP",
      "displayShortName": "Test DE for APP",
      "externalAccess": false,
      "valueType": "INTEGER_ZERO_OR_POSITIVE",
      "displayDescription": "Test DE for APP",
      "dimensionItem": "IQW1OBDMT7j",
      "zeroIsSignificant": false,
      "optionSetValue": false,
      "dimensionItemType": "DATA_ELEMENT",
      "access": {
        "read": true,
        "update": true,
        "externalize": true,
        "delete": true,
        "write": true,
        "manage": true
      }
}  
Web API: http://103.247.238.86:8081/dhis28/api/dataElements/IQW1OB22T7j

Schema Endpoint

Endpoint for providing type introspection, covers almost all types in the system, from data elements to tracked entity instance.
Provides an overview of available properties for each type, including meta properties like uniqueness, required, length of text fields, etc.
Already being used by internal framework code like d2 (will be covered later in the week).

Object Filtering

Object filtering allows you to filter the resultset, both on simple properties like name like, name not like, to more advanced filtering based on recursive filters.
General syntax is:

 ?filter=property-name:operator:value

Available operators include:

Example:

a. Get data elements with id property ID1 or ID2:

 
/api/dataElements?filter=id:eq:ID1&filter=id:eq:ID2

Demo Server: GET https://play.dhis2.org/2.29/api/dataElements/
https://play.dhis2.org/2.29/api/dataElements.json?filter=id:eq:fbfJHSPpUQD

Result: 
"dataElements": 
[{
	"id": "fbfJHSPpUQD",
	"displayName": "ANC 1st visit"
}]

with more fields: 

https://play.dhis2.org/2.29/api/dataElements.json?filter=id:eq:fbfJHSPpUQD&fields=displayName,aggregationType,domainType

b. Get all data elements which has the dataSet with id ID1:

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

Demo Server: 
GET https://play.dhis2.org/2.29/api/dataElements.json
GET https://play.dhis2.org/2.29/api/dataSets.json
https://play.dhis2.org/2.29/api/dataElements?filter=dataSetElements.dataSet.id:eq:VTdjfLXXmoi

Result: Specific dataset with all data elements

c. 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

Demo Server: https://play.dhis2.org/2.29/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]

Demo server: https://play.dhis2.org/2.29/api/dataElements.json?filter=id:in:[fbfJHSPpUQD,cYeuwXTCPkU]

More detail: https://docs.dhis2.org/master/en/developer/html/webapi_metadata_object_filter.html

Field Filtering

Field filtering allows you to filter the fields on each object in the resultset, allowing to narrow the set of properties returned.

General syntax is:

    ?fields=property-a,property-b[property-ba,property-bb]

By default all id object properties will be returned as ID only, Includes presets (set of pre-selected properties):

  ○    all Include all properties (default for object listing) 

  ○    idName Includes displayName and id (default for collection listing)

  ○    identifiable Include properties id, name, code, created, lastUpdated, href

  ○    persisted Includes only properties that are persisted on either side of the graph

  ○    owner Includes only properties that the object owns (i.e. can be used when creating, updating an object)

Examples:

a. Get id and name on the indicators resource:

/api/indicators?fields=id,name

Method: GET 
URL: https://play.dhis2.org/2.29/api/indicators?fields=id,name

Result: 
"indicators": [{
		"name": "ANC 1-3 Dropout Rate",
		"id": "ReUHfIn0pTQ"
	}, {
		"name": "ANC 1 Coverage",
		"id": "Uvn6LCg7dVU"
	}, {
		"name": "ANC 2 Coverage",
		"id": "OdiHJayrsKo"
	},
............
}]
URL: https://play.dhis2.org/2.29/api/indicators?fields=:all

b. Get all indicators with id,name,displayName,code,created,lastUpdated,user,dataSets,indicatorType and display 10 results

URL: https://play.dhis2.org/2.29/api/indicators.json?fields=id,name,displayName,code,created,lastUpdated,user,dataSets,indicatorType&pageSize=10

Result: 
"indicators": [{
		"lastUpdated": "2013-03-21T11:17:44.926",
		"code": "IN_52462",
		"created": "2012-11-05T09:16:29.054",
		"name": "ANC 1-3 Dropout Rate",
		"id": "ReUHfIn0pTQ",
		"displayName": "ANC 1-3 Dropout Rate",
		"indicatorType": {
			"id": "bWuNrMHEoZ0"
		},
		"user": {
			"id": "GOLswS44mh8"
		},
		"dataSets": []
	},
.............
}]

c. Get id and name from dataElements, and id and name from the dataSets on dataElements:

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

Example: 
GET https://play.dhis2.org/2.29/api/dataElements?fields=id,name,dataSets[id,name]

Result: 
  "dataElements": [
        {
            "name": "Accute Flaccid Paralysis (Deaths < 5 yrs)",
            "id": "FTRrcoaog83"
        },
        {
            "name": "Acute Flaccid Paralysis (AFP) follow-up",
            "id": "P3jJH5Tu5VC"
        },
        {
            "name": "Acute Flaccid Paralysis (AFP) new",
            "id": "FQ2o8UBlcrS"
        },
..........
}]

d. Include all fields from dataSets except organisationUnits:

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

Example: 
GET https://play.dhis2.org/2.29/api/dataSets?fields=:all,!organisationUnits

Result: 
 "dataSets": [
        {
            "lastUpdated": "2015-08-09T12:35:36.743",
            "id": "lyLU2wR22tC",
            "href": "https://play.dhis2.org/2.29/api/dataSets/lyLU2wR22tC",
            "created": "2012-06-10T00:36:10.036",
            "name": "ART monthly summary",
            "shortName": "ART 2010",
            "code": "DS_394131",
            "validCompleteOnly": false,
            "publicAccess": "rwr-----",
            "skipOffline": false,
            "compulsoryFieldsCompleteOnly": false,
            "formType": "CUSTOM",
            "version": 22,
            "timelyDays": 0,
            "favorite": false,
            ........................
            "dataEntryForm": {
                "id": "rV5Un1vizeD"
            },
            "categoryCombo": {
                "id": "O4VaNks6tta"
            },
            "legendSet": {
                "id": "k1JHPfXsJND"
            },
            "user": {
                "id": "GOLswS44mh8"
            },
            "dataSetElements": [
                {
                    "dataElement": {
                        "id": "pgzNTiQwMES"
                    },
                    "dataSet": {
                        "id": "lyLU2wR22tC"
                    }
                },
                {
                    "dataElement": {
                        "id": "iCGDtgPA28k"
                    },
                    "dataSet": {
                        "id": "lyLU2wR22tC"
                    }
                },
             .............
}]

e. 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: 
GET https://play.dhis2.org/2.29/api/dataSets/BfMAe6Itzgt?fields=id,name,organisationUnits[:all,!id]

f. Include nameable properties from all indicators: (Includes id, name, shortName, code, description, created and lastUpdated fields)

/api/indicators.json?fields=:nameable

Example: 
GET https://play.dhis2.org/2.29/api/indicators.json?fields=:nameable

Result: 
    "indicators": [
        {
            "lastUpdated": "2013-03-21T11:17:44.926",
            "code": "IN_52462",
            "created": "2012-11-05T09:16:29.054",
            "name": "ANC 1-3 Dropout Rate",
            "id": "ReUHfIn0pTQ",
            "href": "https://play.dhis2.org/2.29/api/indicators/ReUHfIn0pTQ",
            "shortName": "ANC 1-3 Dropout Rate",
            "description": "Indicates the percentage of clients dropping out between the 1st and the 3rd ANC visit. Calculated as the difference between ANC1 and ANC3 by the ANC 1 visits."
        },
        {
            "lastUpdated": "2016-10-10T20:45:57.873",
            "code": "IN_52486",
            "created": "2012-11-13T12:51:32.215",
            "name": "ANC 1 Coverage",
            "id": "Uvn6LCg7dVU",
            "href": "https://play.dhis2.org/2.29/api/indicators/Uvn6LCg7dVU",
            "shortName": "ANC 1 Coverage",
            "description": "Total 1st ANC visits (Fixed and outreach) by expected number of pregnant women."
        },
.............
}]

g. Include identifiable properties from all indicators: (Includes id, name, code, created and lastUpdated fields)

/api/indicators.json?fields=:identifiable

Example: 
GET https://play.dhis2.org/2.29/api/indicators.json?fields=:identifiable

Result: 
    "indicators": [
        {
            "lastUpdated": "2013-03-21T11:17:44.926",
            "code": "IN_52462",
            "created": "2012-11-05T09:16:29.054",
            "name": "ANC 1-3 Dropout Rate",
            "id": "ReUHfIn0pTQ",
            "href": "https://play.dhis2.org/2.29/api/indicators/ReUHfIn0pTQ"
        },
        {
            "lastUpdated": "2016-10-10T20:45:57.873",
            "code": "IN_52486",
            "created": "2012-11-13T12:51:32.215",
            "name": "ANC 1 Coverage",
            "id": "Uvn6LCg7dVU",
            "href": "https://play.dhis2.org/2.29/api/indicators/Uvn6LCg7dVU"
        },
........
   }]

More: https://docs.dhis2.org/2.29/en/developer/html/webapi_metadata_field_filter.html

MOdule-2.1 What is API and Why DHIS2 Web API

“What is an API?” as “a way for one software component
to access another for function and/or data sharing through a well-defined agreement”.
Interface for computer systems to interact
REST architecture style
Resources
HTTP and headers
JSON and XML payloads
Exposes DHIS 2 data model and most services