Web API

+ Basics + The Web API adheres to many of the principles behind the REST architectural style. To mention some few and important ones: + + + 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 a Content-Type 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 Content-Type: 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. 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. +

+ Example: 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 DHIS 2 demo on as basis and we recommend that you follow the provided links with a web browser while reading (log in with admin/district as username/password). 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 chiedom, Bo district) for the month of January 2012. We have now aggregated our data into a statistical report and want to send that data to the national DHIS 2 instance. + The entry point for the Web API running on the demo instance is . The entry point provides a convenient HTML page with links to all of the available resources in the Web API. The resource which is most appropriate for our purpose of sending data values is the dataValueSets resource. A data value set represents a set of data values which have a logical relationship, usually from being captured off the same data entry form. We follow the link to the HTML representation which will take us to . The default representation is a HTML page which provides us with useful instructions on how to interact with this resources. It tells us that we can use the POST verb to send values using a XML format defined by the http://dhis2.org/schema/dxf/2.0 namespace: + <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" period="periodISODate" dataSet="dataSetID" orgUnit="orgUnitID"> + <dataValue dataElement="dataElementID" value="1" /> + <dataValue dataElement="dataElementID" value="2" /> + <dataValue dataElement="dataElementID" value="3" /> +</dataValueSet> + Note: We have omitted the categoryOptionCombo attribute as it is optional and not needed for this example. + 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. The dataValueSets description tells us that the identifier for monthly periods should be on the format yyyyMM which means that we will use 201201 for January 2012. + To obtain the identifier for the data set we return to the the entry point at and follow the embedded link pointing at the dataSets resource located at . From there we find and follow the link to the Mortality < 5 years data set which leads us to . What we did was effectively to retrieve the HTML representation of our data set of interest, and from it we can easily see the identifier, which is 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 facility (org unit). Again the dataSet conveniently provides link to org units which report on it so we search for Ngelehun CHC and follow the link to the HTML representation at , 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" period="201201" dataSet="pBOMPrpg1QX" orgUnit="DiszpKrYNg8"> + <dataValue dataElement="f7n9E0hX8qk" value="12" /> + <dataValue dataElement="Ix2HsbDMLea" value="14" /> + <dataValue dataElement="eY5ehpbEsB7" value="16" /> +</dataValueSet> + 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 "http://apps.dhis2.org/demo/api/dataValueSets" -H "Content-Type:application/xml" -u admin:district -v

+ The command will dispatch a request to the demo Web API with application/xml as content-type and authenticate with basic authentication 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 DHIS 2 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 + In a real-world scenario, looking up identifiers, constructing and dispatching XML messages would be the task of the client software application. This software would probably interact with the more machine-friendly XML and JSON resource representations and not the (human readable) HTML representations like we did in this example. Developing creative and robust consumers of the Web API services is what begins from here. +