dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 478
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Tue 2012-03-20 21:23:52 +0100
message:
  WIP example on web page integration with web api
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-19 20:15:48 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml	2012-03-20 20:23:52 +0000
@@ -4,7 +4,7 @@
   <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>
+    <title>Introduction</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>
@@ -82,4 +82,13 @@
     <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>
+  </section>
 </chapter>