dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #16536
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 476: Added a web api example on how to send messages and replies
------------------------------------------------------------
revno: 476
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Mon 2012-03-19 21:15:48 +0100
message:
Added a web api example on how to send messages and replies
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 16:01:37 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2012-03-19 20:15:48 +0000
@@ -11,7 +11,7 @@
<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'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>
+ <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 an <emphasis role="italic">Accept</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">Accept: 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>
@@ -32,9 +32,9 @@
<dataValue dataElement="dataElementID" value="3" />
</dataValueSet></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>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 < 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 < 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>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><dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" period="201201" dataSet="pBOMPrpg1QX" orgUnit="DiszpKrYNg8">
<dataValue dataElement="f7n9E0hX8qk" value="12" />
@@ -47,4 +47,39 @@
<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 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>
+ <title>Example: Writing and reading messages</title>
+ <para>DHIS 2 features a mechanism for sending messages for purposes such as user feedback, notifications and general information to users. Messages are delivered to the DHIS 2 message inbox but can also be sent to the user's email addresses and mobile phones as SMS. In this example we will see how we can utilize the Web API to send and read messages. We will pretend to be the <emphasis role="italic">DHIS Administrator</emphasis> user and send a message to the <emphasis role="italic">Mobile</emphasis> user. We will then pretend to be the mobile user and read our new message.</para>
+ <para>The resource we need to interact with when sending and reading messages is the <emphasis role="italic">messageConversations</emphasis> resource. We start by visiting the Web API entry point at <ulink url="http://apps.dhis2.org/demo/api"/> where we find and follow the link to the <emphasis role="italic">messageConversations</emphasis> resource at <ulink url="http://apps.dhis2.org/demo/api/messageConversations"/>. The description tells us that we can use a POST request to create a new message using the following XML format:</para>
+ <para><screen><message xmlns="http://dhis2.org/schema/dxf/2.0">
+ <subject>This is the subject</subject>
+ <text>This is the text</text>
+ <users>
+ <user id="user1ID" />
+ <user id="user2ID" />
+ <user id="user3ID" />
+ </users>
+</message></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><message xmlns="http://dhis2.org/schema/dxf/2.0">
+ <subject>Mortality data reporting</subject>
+ <text>Have you reported data for the Mortality data set for January 2012?</text>
+ <users>
+ <user id="PhzytPW3g2J" />
+ </users>
+</message></screen></para>
+ <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 "http://apps.dhis2.org/demo/api/messageConversations" -H "Content-Type:application/xml" -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 "http://apps.dhis2.org/demo/api/messageConversations" -H "Accept:application/xml" -u mobile:district -X GET -v</code></para>
+ <para>In response we get the following XML:</para>
+ <para><screen><messageConversations xmlns="http://dhis2.org/schema/dxf/2.0" link="http://apps.dhis2.org/demo/api/messageConversations">
+ <messageConversation name="Mortality data reporting" id="ZjHHSjyyeJ2" link="http://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2"/>
+ <messageConversation name="DHIS version 2.7 is deployed" id="GDBqVfkmnp2" link="http://apps.dhis2.org/demo/api/messageConversations/GDBqVfkmnp2"/>
+</messageConversations></screen></para>
+ <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 "Yes the Mortality data set has been reported" "http://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2" -H "Content-Type:text/plain" -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>
</chapter>
