dhis2-devs team mailing list archive

Thread
Date

[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 473: Added chapter on web api

To: DHIS 2 developers <dhis2-devs@xxxxxxxxxxxxxxxxxxx>
From: noreply@xxxxxxxxxxxxx
Date: Mon, 19 Mar 2012 15:47:11 -0000
Reply-to: noreply@xxxxxxxxxxxxx
Sender: bounces@xxxxxxxxxxxxx

------------------------------------------------------------
revno: 473
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Mon 2012-03-19 16:46:00 +0100
message:
  Added chapter on web api
added:
  src/docbkx/en/dhis2_user_man_web_api.xml
renamed:
  src/docbkx/en/resources/images/data_dimensions/dhis_input_output.JPG => src/docbkx/en/resources/images/data_dimensions/dhis_input_output.jpg
modified:
  src/docbkx/en/dhis2_user_man_data_dimensions.xml
  src/docbkx/en/dhis2_user_manual_en.xml
  src/docbkx/en/resources/css/docbook_bsd.css


--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs

Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription

=== modified file 'src/docbkx/en/dhis2_user_man_data_dimensions.xml'
--- src/docbkx/en/dhis2_user_man_data_dimensions.xml	2011-04-28 17:07:59 +0000
+++ src/docbkx/en/dhis2_user_man_data_dimensions.xml	2012-03-19 15:46:00 +0000
@@ -370,7 +370,7 @@
 <screenshot>
           <mediaobject>
             <imageobject>
-              <imagedata width="60%" align="center" fileref="resources/images/data_dimensions/dhis_input_output.JPG" format="JPG"/>
+              <imagedata width="60%" align="center" fileref="resources/images/data_dimensions/dhis_input_output.jpg" format="JPG"/>
             </imageobject>
           </mediaobject>
         </screenshot>

=== added file 'src/docbkx/en/dhis2_user_man_web_api.xml'
--- src/docbkx/en/dhis2_user_man_web_api.xml	1970-01-01 00:00:00 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml	2012-03-19 15:46:00 +0000
@@ -0,0 +1,50 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
+<chapter>
+  <title>Web API</title>
+  <para>The Web API is a component which makes it possible for external systems  to access and manipulate  data stored in an instance of DHIS 2. 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 DHIS 2 modules.</para>
+  <section>
+    <title>Basics</title>
+    <para>The Web API adheres to many of the principles behind the REST architectural style. To mention some few and important ones:</para>
+    <orderedlist>
+      <listitem>
+        <para>The fundamental building blocks are referred to as <emphasis role="italic">resources</emphasis>. 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 <emphasis role="italic">representations</emphasis>. A representation is a view of a resource&apos;s state at any given time. For instance, the <emphasis role="italic">reportTable</emphasis> 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.</para>
+      </listitem>
+      <listitem>
+        <para>All resources can be uniquely identified by a <emphasis role="italic">URI</emphasis> (also referred to as <emphasis role="italic">URL</emphasis>). All resources have a default representation. You can indicate that you are interested in a specific representation  by supplying a <emphasis role="italic">Content-Type</emphasis> HTTP header, a file extension or a <emphasis role="italic">format</emphasis> query parameter. So in order to retrieve the PDF representation of a report table you can  supply a <emphasis role="italic">Content-Type: application/pdf</emphasis> header or append <emphasis role="italic">.pdf</emphasis> or <emphasis role="italic">?format=pdf</emphasis> to your request URL.</para>
+      </listitem>
+      <listitem>
+        <para>Interactions with the API requires correct use of HTTP <emphasis role="italic">methods</emphasis> or <emphasis role="italic">verbs</emphasis>. This implies that for a resource you must issue a  <emphasis role="italic">GET</emphasis> request when you want to retrieve it, <emphasis role="italic">POST</emphasis> request when you want to create one, <emphasis role="italic">PUT</emphasis> when you want to update it and <emphasis role="italic">DELETE</emphasis> 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. <emphasis role="italic">/reportTable/iu8j/hYgF6t</emphasis>, where the last part is the report table identifier.</para>
+      </listitem>
+      <listitem>
+        <para>Resource representations are <emphasis role="italic">linkable</emphasis>, 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 <emphasis role="italic">reportTable</emphasis> resource  through the embedded links using your preferred representation format.</para>
+      </listitem>
+    </orderedlist>
+    <para>While all of this might sound complicated, the Web API is actually very simple to use. We will proceed with a few practical examples.</para>
+  </section>
+  <section>
+    <title>Example: Sending data values</title>
+    <para>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 <ulink url="http://apps.dhis2.org/demo"/> as basis and we recommend that you follow the provided links with a web browser while reading (log in with <emphasis role="italic">admin</emphasis><emphasis role="italic">/district</emphasis> as username/password). We assume that we have collected case-based data using a simple software client running on mobile phones for the  <emphasis role="italic">Mortality &lt;5 years</emphasis> data set in the community of <emphasis role="italic">Ngelehun CHC</emphasis> (in <emphasis role="italic">Badjia</emphasis> chiedom, <emphasis role="italic">Bo</emphasis> 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.</para>
+    <para>The entry point for the Web API running on the demo instance is <ulink url="http://apps.dhis2.org/demo/api"/>. 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 <emphasis role="italic">dataValueSets</emphasis> 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 <ulink url="http://apps.dhis2.org/demo/api/dataValueSets"/>. 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 <emphasis role="italic">http://dhis2.org/schema/dxf/2.0</emphasis> namespace:</para>
+    <para><screen>&lt;dataValueSet xmlns=&quot;http://dhis2.org/schema/dxf/2.0&quot; period=&quot;periodISODate&quot; dataSet=&quot;dataSetID&quot; orgUnit=&quot;orgUnitID&quot;&gt;
+  &lt;dataValue dataElement=&quot;dataElementID&quot; value=&quot;1&quot; /&gt;
+  &lt;dataValue dataElement=&quot;dataElementID&quot; value=&quot;2&quot; /&gt;
+  &lt;dataValue dataElement=&quot;dataElementID&quot; value=&quot;3&quot; /&gt;
+&lt;/dataValueSet&gt;</screen></para>
+    <para><emphasis role="italic">Note:</emphasis> We have omitted the <emphasis role="italic">categoryOptionCombo</emphasis> attribute as it is optional and not needed for this example.</para>
+    <para>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 <emphasis role="italic">dataValueSets</emphasis> description tells us that the identifier for monthly periods should be on the format <emphasis role="italic">yyyyMM</emphasis> which means that we will use <emphasis role="italic">201201</emphasis> for January 2012.</para>
+    <para>To obtain the identifier for the data set we return to the the entry point at <ulink url="http://apps.dhis2.org/demo/api"/> and follow the embedded link pointing at the <emphasis role="italic">dataSets</emphasis> resource located at <ulink url="http://apps.dhis2.org/demo/api/dataSets"/>. From there we find and follow the link to the <emphasis role="italic">Mortality &lt; 5 years</emphasis> data set which leads us to <ulink url="http://apps.dhis2.org/demo/api/dataSets/pBOMPrpg1QX"/>. 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 <emphasis role="italic">pBOMPrpg1QX</emphasis>. The resource representation for the <emphasis role="italic">Mortality &lt; 5 years</emphasis> 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: <emphasis role="italic">Measles</emphasis> with id <emphasis role="italic">f7n9E0hX8qk</emphasis>, <emphasis role="italic">Dysentery</emphasis> with id <emphasis role="italic">Ix2HsbDMLea</emphasis> and <emphasis role="italic">Cholera</emphasis> with id <emphasis role="italic">eY5ehpbEsB7</emphasis>.</para>
+    <para>What remains is to get hold of the identifier of the facility (org unit). Again the <emphasis role="italic">dataSet</emphasis> conveniently provides link to org units which report on it so we search for<emphasis role="italic"> Ngelehun CHC</emphasis> and follow the link to the HTML representation at <ulink url="http://apps.dhis2.org/demo/api/organisationUnits/DiszpKrYNg8"/>, which tells us that the identifier of this org unit is <emphasis role="italic">DiszpKrYNg8</emphasis>.</para>
+    <para>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:</para>
+    <para><screen>&lt;dataValueSet xmlns=&quot;http://dhis2.org/schema/dxf/2.0&quot; period=&quot;201201&quot; dataSet=&quot;pBOMPrpg1QX&quot; orgUnit=&quot;DiszpKrYNg8&quot;&gt;
+  &lt;dataValue dataElement=&quot;f7n9E0hX8qk&quot; value=&quot;12&quot; /&gt;
+  &lt;dataValue dataElement=&quot;Ix2HsbDMLea&quot; value=&quot;14&quot; /&gt;
+  &lt;dataValue dataElement=&quot;eY5ehpbEsB7&quot; value=&quot;16&quot; /&gt;
+&lt;/dataValueSet&gt;</screen></para>
+    <para>To perform  functional testing we will use the cURL tool (<ulink url="http://curl.haxx.se"/>) which provides an easy way of transferring data using HTTP. First we save the data value set XML content in a file called <emphasis role="italic">datavalueset.xml</emphasis> . From the directory where this file resides we invoke the following from the command line:</para>
+    <para><code>curl -d @datavalueset.xml &quot;http://apps.dhis2.org/demo/api/dataValueSets&quot; -H &quot;Content-Type:application/xml&quot; -u admin:district -v</code></para>
+    <para>The command will dispatch a request to the demo Web API with <emphasis role="italic">application/xml</emphasis> as content-type and authenticate with basic authentication using admin/district as username/password. If all goes well this will return a <emphasis role="italic">200 OK</emphasis> 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.</para>
+    <para>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, <emphasis role="italic">415 Unsupported Media Type</emphasis> is returned. If the XML content is invalid according to the DXF namespace, <emphasis role="italic">400 Bad Request</emphasis> is returned. If you </para>
+    <para>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.</para>
+  </section>
+</chapter>

=== modified file 'src/docbkx/en/dhis2_user_manual_en.xml'
--- src/docbkx/en/dhis2_user_manual_en.xml	2012-03-16 06:42:02 +0000
+++ src/docbkx/en/dhis2_user_manual_en.xml	2012-03-19 15:46:00 +0000
@@ -31,6 +31,7 @@
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_NBITS.xml" encoding="UTF-8"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_mobile.xml" encoding="UTF-8"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_data_dimensions.xml"/>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_web_api.xml"/>
   <appendix>
     <title> DHIS Documentation Guide</title>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_documentation_guide.xml" encoding="UTF-8" xpointer="docs_1"/>

=== modified file 'src/docbkx/en/resources/css/docbook_bsd.css'
--- src/docbkx/en/resources/css/docbook_bsd.css	2012-03-19 10:41:57 +0000
+++ src/docbkx/en/resources/css/docbook_bsd.css	2012-03-19 15:46:00 +0000
@@ -129,7 +129,11 @@
 BODY P B.APPLICATION {  
 	color: #000000;  
 }  
-  
+
+.ITALIC {
+	font-style: italic;
+}
+
 .FILENAME {  
 	color: #007a00;  
 }  

=== renamed file 'src/docbkx/en/resources/images/data_dimensions/dhis_input_output.JPG' => 'src/docbkx/en/resources/images/data_dimensions/dhis_input_output.jpg'