dhis2-devs team mailing list archive

Thread
Date

[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 479: Finished web page / web api example

To: DHIS 2 developers <dhis2-devs@xxxxxxxxxxxxxxxxxxx>
From: noreply@xxxxxxxxxxxxx
Date: Wed, 21 Mar 2012 14:07:12 -0000
Reply-to: noreply@xxxxxxxxxxxxx
Sender: bounces@xxxxxxxxxxxxx

------------------------------------------------------------
revno: 479
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Wed 2012-03-21 14:59:25 +0100
message:
  Finished web page / web api example
modified:
  src/docbkx/en/dhis2_user_man_web_api.xml


--
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_web_api.xml'
--- src/docbkx/en/dhis2_user_man_web_api.xml	2012-03-20 20:23:52 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml	2012-03-21 13:59:25 +0000
@@ -26,25 +26,26 @@
     <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;
+    <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>
+&lt;/dataValueSet&gt;</screen>
     <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> resource 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> representation 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;
+    <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>
+&lt;/dataValueSet&gt;</screen>
     <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 command will dispatch a request to the demo Web API,  set <emphasis role="italic">application/xml</emphasis> as the content-type and  authenticate 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, <emphasis role="italic">401 Unauthorized</emphasis> 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 provide an invalid identifier in the XML content, <emphasis role="italic">409 Conflict</emphasis> is returned together with a descriptive message.</para>
+    <para>In this example, cURL will authenticate to the server through <emphasis role="italic">basic authentication</emphasis> using our supplied username and password as credentials. 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 and   supplied as the value of the <emphasis role="italic">Authorization</emphasis> HTTP header. An important note is that this authentication scheme provides no security since the username and password is sent in plain text and can be easily decoded. Using it is  recommended only if the server is using SSL/TLS (HTTPS) to encrypt communication between itself and the client.</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-friendly HTML representations like we  did in this example. Developing creative and robust consumers of the Web API services begins  here.</para>
   </section>
   <section>
@@ -61,34 +62,46 @@
   &lt;/users&gt;
 &lt;/message&gt;</screen></para>
     <para>Since we want to send a message to our friend the mobile user we need to look up her identifier. We do so by going to the  Web API entry point and follow the link to the <emphasis role="italic">users</emphasis> resource at <ulink url="http://apps.dhis2.org/demo/api/users"/>. We continue by following link to the DHIS Administrator at <ulink url="http://apps.dhis2.org/demo/api/users/PhzytPW3g2J"/> where we learn that her identifier is <emphasis role="italic">PhzytPW3g2J</emphasis>. We are now ready to put our XML message together to form a message where we want to ask the mobile user whether she has reported data for January 2012:</para>
-    <para><screen>&lt;message xmlns=&quot;http://dhis2.org/schema/dxf/2.0&quot;&gt;
+    <screen>&lt;message xmlns=&quot;http://dhis2.org/schema/dxf/2.0&quot;&gt;
   &lt;subject&gt;Mortality data reporting&lt;/subject&gt;
   &lt;text&gt;Have you reported data for the Mortality data set for January 2012?&lt;/text&gt;
   &lt;users&gt;
     &lt;user id=&quot;PhzytPW3g2J&quot; /&gt;
   &lt;/users&gt;
-&lt;/message&gt;</screen></para>
+&lt;/message&gt;</screen>
     <para>To test this we save the XML content into a file called <emphasis role="italic">message.xml</emphasis>. We use cURL to dispatch the message the the DHIS 2 demo instance where we indicate that the content-type is XML and authenticate as the <emphasis role="italic">admin</emphasis> user:</para>
     <para><code>curl -d @message.xml &quot;http://apps.dhis2.org/demo/api/messageConversations&quot; -H &quot;Content-Type:application/xml&quot; -u admin:district -X POST -v</code></para>
     <para>If all is well we receive a <emphasis role="italic">201 Created</emphasis> HTTP status code. Also note that we receive a <emphasis role="italic">Location </emphasis>HTTP header which value  informs us of the URL of the newly  created message conversation resource - this can be used by a consumer to perform further action.</para>
     <para>We will now pretend to be the mobile user and read the message which was just sent by dispatching a GET request to the <emphasis role="italic">messageConversations</emphasis> resource. We supply an <emphasis role="italic">Accept</emphasis> header with <emphasis role="italic">application/xml</emphasis> as the value to indicate that we are interested in the XML resource representation and we authenticate as the <emphasis role="italic">mobile</emphasis> user:</para>
     <para><code>curl &quot;http://apps.dhis2.org/demo/api/messageConversations&quot; -H &quot;Accept:application/xml&quot; -u mobile:district -X GET -v</code></para>
     <para>In response we get the following XML:</para>
-    <para><screen>&lt;messageConversations xmlns=&quot;http://dhis2.org/schema/dxf/2.0&quot; link=&quot;http://apps.dhis2.org/demo/api/messageConversations&quot;&gt;
+    <screen>&lt;messageConversations xmlns=&quot;http://dhis2.org/schema/dxf/2.0&quot; link=&quot;http://apps.dhis2.org/demo/api/messageConversations&quot;&gt;
   &lt;messageConversation name=&quot;Mortality data reporting&quot; id=&quot;ZjHHSjyyeJ2&quot; link=&quot;http://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2&quot;/&gt;
   &lt;messageConversation name=&quot;DHIS version 2.7 is deployed&quot; id=&quot;GDBqVfkmnp2&quot; link=&quot;http://apps.dhis2.org/demo/api/messageConversations/GDBqVfkmnp2&quot;/&gt;
-&lt;/messageConversations&gt;</screen></para>
+&lt;/messageConversations&gt;</screen>
     <para>From the response we are able to read the identifier of the newly sent message which is <emphasis role="italic">ZjHHSjyyeJ2</emphasis>. Note that the link to the specific resource is embedded and available for  consumers to use. From the description at <ulink url="http://apps.dhis2.org/demo/api/messageConversations"/> we learned that we can reply directly to an existing message conversation once we know the URL by including the message text as the  request payload (body). We are now able to construct a URL for sending our reply:</para>
     <para><code>curl -d &quot;Yes the Mortality data set has been reported&quot; &quot;http://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2&quot; -H &quot;Content-Type:text/plain&quot; -u mobile:district -X POST -v</code> </para>
     <para>If all went according to plan you will receive a <emphasis role="italic">200 OK</emphasis> status code.</para>
   </section>
   <section>
     <title>Example: Embedding reports in web pages</title>
-    <para>In this example we will see how we can build a simple web page  where dynamic data such as tabular reports and charts  is pulled from the DHIS Web API. </para>
-    <para>The Web API contains several resources which are useful for data analysis: <emphasis role="italic">report</emphasis>, <emphasis role="italic">reportTable</emphasis>, <emphasis role="italic">chart</emphasis>, <emphasis role="italic">map</emphasis> and <emphasis role="italic">document</emphasis>. Dispatching  GET requests to the mentioned URLs will return the relevant meta-data information for each resource. For all of those resources it is valid to append <emphasis role="italic">/data</emphasis> to the URL. The response such GET-requests will convey information about the aggregated data related to the resource. This information can be represented in a variety of formats including HTML, PDF, Excel, PNG and Jasper, as we will see later.</para>
-    <para>We  begin as usual at the Web API entrypoint at <ulink url="http://apps.dhis2.org/demo/api"/>. We look for a relevant tabular report by following the <emphasis role="italic">reportTables</emphasis> link to <ulink url="http://apps.dhis2.org/demo/api/reportTables"/>. From this list we decide that we are interested in the &quot;District Maternal Health&quot; report and follow the link to <ulink url="http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1"/>. This resource provides meta-data information about the report table. It also advertises a link for retrieving analytical data which can be constructed by appending /data to the URL. Following this link will lead us to <ulink url="http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1/data"/>. As we can see we are provided with a  report table in HTML format, which is the default representation format. </para>
-    <para>As stated in the introduction there are three ways of indicating which resource representation format you want for the response. The easiest alternative when used directly in web pages is to append a file suffix to the URL. We assume that we are interested in the PDF representation and indicate that by appending .pdf to our URL: <ulink url="http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1/data.pdf"/>. Go ahead and try out all valid extensions for this resource which are <emphasis role="italic">.html</emphasis>, <emphasis role="italic">.pdf</emphasis>, <emphasis role="italic">.xls</emphasis> and <emphasis role="italic">.csv</emphasis>.</para>
-    <para>Also note that the report table can be parameterized with an organisation unit and a period by supplying a <emphasis role="italic">ou</emphasis> and <emphasis role="italic">pe</emphasis> query parameter together with an organisation unit  identifier and period string respectively in the URL. If not provided the Web API will use the top-most organisation unit in the hierarchy and the last time period for the report table content. The organisation unit identifier can be looked up by going to the Web API entrypoint, following the link to the organisationUnits resouce. For our example we will request that <emphasis role="italic">Bo</emphasis> district whith identifier <emphasis role="italic">O6uvpzGd5pu</emphasis> is used as the organisation unit: <ulink url="http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1/data?ou=O6uvpzGd5pu"/>.</para>
-    <para>Autenticating to a DHIS instance from a web page can be done in  many ways, and each method has advantages and downsides.</para>
+    <para>In this example we will see how we can build a simple web page  where dynamic data such as tabular reports is pulled from the DHIS Web API. A full example on how this can done is available at <ulink url="http://apps.dhis2.org/portal"/>.</para>
+    <para>The Web API contains several resources which are useful for data analysis: <emphasis role="italic">report</emphasis>, <emphasis role="italic">reportTable</emphasis>, <emphasis role="italic">chart</emphasis>, <emphasis role="italic">map</emphasis> and <emphasis role="italic">document</emphasis>. Dispatching  GET requests to the mentioned resources will return meta-data information such as name and the date it was last updated. All these resources have an associated <emphasis role="italic">data</emphasis> resource which produces a data view of  related aggregated data - also  known as  reports, charts and maps. You can follow the links or simply append <emphasis role="italic">/data</emphasis> to the URL to arrive at it. This information can be represented in a variety of formats including HTML, PDF, Excel, PNG and Jasper, as we will see in the next section.</para>
+    <para>We  start as usual at the Web API entrypoint at <ulink url="http://apps.dhis2.org/demo/api"/>. We look for a relevant  report table by following the <emphasis role="italic">reportTables</emphasis> link to <ulink url="http://apps.dhis2.org/demo/api/reportTables"/>. We assume that we are interested in the &quot;District Maternal Health&quot; report and follow the link to <ulink url="http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1"/>. This resource provides meta-data information about the report table. From here we can follow the link to the default data view of aggregated data, which leads us to  <ulink url="http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1/data"/>. As we can see we are provided with a  report table in HTML format, which is the default representation format for report tables.</para>
+    <para>As stated in the introduction there are three ways of indicating which resource representation format you prefer for the response. The most suitable alternative for direct use in web pages is to append a file suffix to the URL. We assume that we are interested in the PDF representation and indicate that by appending <emphasis role="italic">.pdf</emphasis> to our URL: <ulink url="http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1/data.pdf"/>. Go ahead and try out all valid extensions for this resource which are <emphasis role="italic">.html</emphasis>, <emphasis role="italic">.pdf</emphasis>, <emphasis role="italic">.xls</emphasis> and <emphasis role="italic">.csv</emphasis>.</para>
+    <para>The report table can be parameterized with an organisation unit and a period by supplying a <emphasis role="italic">ou</emphasis> and <emphasis role="italic">pe</emphasis> query parameter accompanied with an organisation unit  identifier and period string  in the URL. If not provided the Web API will use the top-most organisation unit in the hierarchy and the last  period for the report table content. The organisation unit identifier can be looked up by going to the Web API entrypoint and follow the link to the <emphasis role="italic">organisationUnits</emphasis> resouce. For our example we will use <emphasis role="italic">Bo</emphasis> district whith identifier <emphasis role="italic">O6uvpzGd5pu</emphasis> as the organisation unit: <ulink url="http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1/data?ou=O6uvpzGd5pu"/>. From the HTML representation we can  see that the report now contains data for <emphasis role="italic">Bo</emphasis> district. These URLs can  simply  be used in links embedded in the web page like this:</para>
+    <screen>&lt;a href=&quot;http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1/data.pdf?ou=O6uvpzGd5pu&quot;&gt;Maternal Health Bo District 2012&lt;/a&gt;</screen>
+    <para>There are many ways to authenticate over the Web and each method has its advantages and disadvantages. For this example we will use an  approach where we emulate a  login from the web-based login form. To help us we will use the <emphasis role="italic">jQuery</emphasis>  javascript library. This javascript code should be embedded in the <emphasis role="italic">head</emphasis> section of the Web page:</para>
+    <screen>jQuery(document).ready(function() {
+  var base = &quot;http://apps.dhis2.org/demo/&quot;;
+  $.post( base + &quot;dhis-web-commons-security/login.action&quot;,{
+      j_username: &quot;admin&quot;, j_password: &quot;district&quot; 
+    },
+    setLinks
+  );
+});</screen>
+    <para>In this code block we ask jQuery to send a POST request to the standard authentication point with two name-value pairs containing the username and password information. We assume that the user has the necessary authorities to view reports in the DHIS 2 Web API. If  authentication was successful the server will send a HTTP cookie in the response with a session identifier. This will make sure that the current user is authorized to view reports for up to 60 minutes.</para>
+    <para>Caveat:  The username and password will be present in the web page in plain text. Make sure  you create a dedicated user in DHIS 2 for this purpose given only the minimum authorities required.</para>
+    <para>For a full example visit <ulink url="http://apps.dhis2.org/portal"/> and view the page source in a browser. Note that the example web page is hosted within the same domain (apps.dhis2.org) as the demo DHIS 2 instance. This is done to avoid issues related to the &quot;same origin policy&quot;, a concept which prevents scripts hosted on one domain to access resources running on another. While one can circumvent this through techniques such as <emphasis role="italic">CORS</emphasis>, there are none which have wide browser support at the moment. Therefore we recommend hosting web pages and portals on the same domain. Techniques using reverse proxies described in the &quot;installation&quot; chapter can be useful in this regard.</para>
   </section>
 </chapter>