dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #23331
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 773: minor update of event docs, include PUT and DELETE
------------------------------------------------------------
revno: 773
committer: Morten Olav Hansen <mortenoh@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Fri 2013-07-05 16:55:38 +0700
message:
minor update of event docs, include PUT and DELETE
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 2013-06-09 21:26:38 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2013-07-05 09:55:38 +0000
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
+<!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>
@@ -26,10 +26,8 @@
<title>Authentication</title>
<para>In order to interoperate with the Web API you will have to authenticate using <emphasis role="italic">Basic authentication</emphasis>. 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, prefixed Basic and supplied as the value of the <emphasis role="italic">Authorization</emphasis> HTTP header. More formally that is<code> Authorization: Basic base64encode(username:password)</code> 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. Most DHIS 2 deployments typically use SSL today - consider it a hard requirement to provide secure interactions with the Web API.</para>
<para>If you are building a form-based web application and want to authenticate using a web form
- you can have the form send a POST request to the login endpoint in DHIS which is <emphasis
- role="italic">/dhis-web-commons-security/login.action</emphasis> . Two request parameters,
- <emphasis role="italic">j_username</emphasis> and <emphasis role="italic"
- >j_password</emphasis>, containing the username and password in clear-text respectively, are
+ you can have the form send a POST request to the login endpoint in DHIS which is <emphasis role="italic">/dhis-web-commons-security/login.action</emphasis> . Two request parameters,
+ <emphasis role="italic">j_username</emphasis> and <emphasis role="italic">j_password</emphasis>, containing the username and password in clear-text respectively, are
expected. The browser will then receive a cookie which will be used for authentication for
subsequent requests.</para>
<para>You can verify and get information about the currently authenticated user by making a GET
@@ -130,12 +128,10 @@
</section>
<section>
<title>Browsing the Web API</title>
- <para>The entry point for browsing the Web API is <emphasis role="italic"
- >/api/resources</emphasis>. This resource provide links to all available resources. Four
+ <para>The entry point for browsing the Web API is <emphasis role="italic">/api/resources</emphasis>. This resource provide links to all available resources. Four
resource representation formats are consistently available for all resources: HTML, XML, JSON
and JSONP. Some resources will have other formats available, like MS Excel, PDF, CSV and PNG.
- To explore the API from a web browser, navigate to the <emphasis role="italic"
- >/api/resources</emphasis> entry point and follow the links to your desired resource, for
+ To explore the API from a web browser, navigate to the <emphasis role="italic">/api/resources</emphasis> entry point and follow the links to your desired resource, for
instance <emphasis role="italic">/api/resources/dataElements</emphasis>. For all resources
which return a list of elements certain query parameters can be used to modify the
response:</para>
@@ -197,15 +193,13 @@
using the <emphasis role="italic">query</emphasis> path variable. In this example we query for
all data elements with the word "anaemia" in the name:</para>
<screen>/api/dataElements/query/anaemia</screen>
- <para>You can search for elements through the id, name and code property using the <emphasis
- role="italic">search</emphasis> path variable. In this example we search for a data element
+ <para>You can search for elements through the id, name and code property using the <emphasis role="italic">search</emphasis> path variable. In this example we search for a data element
with the word "DE_34" as id, name or
code:<screen>/api/dataElements/search/DE_34</screen></para>
</section>
<section>
<title>Working with the meta-data API</title>
- <para>The meta-data resource can be accessed at <emphasis role="italic"
- >/api/metaData</emphasis>. This resource lets you read and write the full set of meta-data.
+ <para>The meta-data resource can be accessed at <emphasis role="italic">/api/metaData</emphasis>. This resource lets you read and write the full set of meta-data.
This section will give a basic introduction to working with this API. For specific
synchronization issues, please see the integration chapter.</para>
<para>By default, interacting with<emphasis role="italic"> /api/metaData</emphasis> using the
@@ -293,8 +287,7 @@
<emphasis role="bold">Example: Get a filtered set of meta-data that was updated since August 1
2012</emphasis>
</para>
- <para>As described in the last section, there is a number of options you can apply to <emphasis
- role="italic">/api/metaData</emphasis> to give you a filtered view. The use-case we will be
+ <para>As described in the last section, there is a number of options you can apply to <emphasis role="italic">/api/metaData</emphasis> to give you a filtered view. The use-case we will be
looking into here is where you want a nightly job that synchronizes organisation units. We
will be using <emphasis role="italic">cURL</emphasis> as the HTTP
client.<screen>curl -H "Accept: application/xml" -u admin:district "http://apps.dhis2.org/demo/api/metaData?assumeTrue=false&organisationUnits=true&lastUpdated=01/08/2012";</screen></para>
@@ -315,14 +308,11 @@
<section>
<title>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
+ 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 <5 years</emphasis> data set in the
- community of <emphasis role="italic">Ngelehun CHC</emphasis> (in <emphasis role="italic"
- >Badjia</emphasis> chiefdom, <emphasis role="italic">Bo</emphasis> district) for the month
+ community of <emphasis role="italic">Ngelehun CHC</emphasis> (in <emphasis role="italic">Badjia</emphasis> chiefdom, <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>
@@ -334,10 +324,8 @@
</dataValueSet></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. Please refer to the date and period section above for time formats.</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 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
+ <para>To obtain the identifier for the data set we return to 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
@@ -347,8 +335,7 @@
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>
+ 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>
<screen><dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="pBOMPrpg1QX"
@@ -357,8 +344,7 @@
<dataValue dataElement="Ix2HsbDMLea" value="14"/>
<dataValue dataElement="eY5ehpbEsB7" value="16"/>
</dataValueSet></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
+ <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 "http://apps.dhis2.org/demo/api/dataValueSets" -H "Content-Type:application/xml" -u admin:district -v</code></para>
@@ -373,12 +359,9 @@
to as anonymous events), single event with registration and multiple events with registration.
Registration implies that the data is linked to a person which is identified using some sort
of identifier. Only single event with no registration is supported in DXF 2 currently.</para>
- <para>To send events to DHIS 2 you must interact with the <emphasis role="italic"
- >events</emphasis> resource. The approach to sending events is similar to sending aggregate
+ <para>To send events to DHIS 2 you must interact with the <emphasis role="italic">events</emphasis> resource. The approach to sending events is similar to sending aggregate
data values. You will need a <emphasis role="italic">programId</emphasis> which can be looked
- up using the <emphasis role="italic">programs</emphasis> resource, an <emphasis role="italic"
- >organisationUnitId</emphasis> which can be looked up using the <emphasis role="italic"
- >organisationUnits</emphasis> resource, and a list of valid data element identifiers which
+ up using the <emphasis role="italic">programs</emphasis> resource, an <emphasis role="italic">organisationUnitId</emphasis> which can be looked up using the <emphasis role="italic">organisationUnits</emphasis> resource, and a list of valid data element identifiers which
can be looked up using the <emphasis role="italic">dataElements</emphasis> resource. </para>
<para>An example payload in XML format where we send events from the "Inpatient morbidity and
mortality" program for the "Ngelehun CHC" facility in the demo database can be seen
@@ -392,8 +375,7 @@
<dataValue dataElement="msodh3rEMJa" value="2013-05-18" />
</dataValues>
</event></screen>
- <para>To perform some testing we can save the XML payload as a file called<emphasis
- role="italic"> events.xml</emphasis> and send it as a POST request to the events resource in
+ <para>To perform some testing we can save the XML payload as a file called<emphasis role="italic"> events.xml</emphasis> and send it as a POST request to the events resource in
the API using curl with the following command:</para>
<screen>curl -d @events.xml "http://apps.dhis2.org/demo/api/events"; -H "Content-Type:application/xml" -u admin:district -v</screen>
<para>The same payload in JSON format looks like this:</para>
@@ -413,8 +395,7 @@
{ "dataElement": "msodh3rEMJa", "value": "2013-05-18" }
]
}</screen>
- <para>To send this you can save it to a file called <emphasis role="italic"
- >events.json</emphasis> and use curl like this:</para>
+ <para>To send this you can save it to a file called <emphasis role="italic">events.json</emphasis> and use curl like this:</para>
<screen>curl -d @events.xml "localhost:8080/api/events" -H "Content-Type:application/json" -u admin:district -v</screen>
<para>We also support sending multiple events at the same time. A payload in XML format might
look like this: (Caution: this format might change slightly in version 2.13)</para>
@@ -472,6 +453,15 @@
] }
]
}</screen>
+ <para>(from 2.13) as part of the import summary you will also get the UID reference to the event
+ you just sent, together with a href element which points to the server location of this event. </para>
+ <para><emphasis role="bold">Update</emphasis>: To update an existing event, the format of the
+ payload is the same, but the URL you are posting to must add the UID reference to the end of
+ the URL string and the request must be PUT.
+ <screen>curl -X PUT -d @updated_event.xml "localhost:8080/api/events/Abcas12322" -H "Content-Type:application/xml" -u admin:district -v</screen><screen>curl -X PUT -d @updated_event.json "localhost:8080/api/events/Abcas12322" -H "Content-Type:application/json" -u admin:district -v</screen></para>
+ <para><emphasis role="bold">Delete</emphasis>: To delete an existing event, all you need is to
+ send a DELETE request with a UID reference to the server you are
+ using.<screen>curl -X DELETE "localhost:8080/api/events/Abcas12322" -u admin:district -v</screen></para>
<para>The table below describes the meaning of each element. Most elements should be fairly
self-explanatory.</para>
<para>
@@ -545,14 +535,14 @@
<entry>dataElementId</entry>
<entry>string</entry>
<entry>true</entry>
- <entry></entry>
+ <entry/>
<entry>UID of data element</entry>
</row>
<row>
<entry>value</entry>
<entry>string</entry>
<entry>true</entry>
- <entry></entry>
+ <entry/>
<entry>Data value or measure for this event</entry>
</row>
</tbody>
@@ -765,11 +755,9 @@
<para><code>curl
"http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&dataSet=BfMAe6Itzgt&startDate=2013-01-01&endDate=2013-01-31&orgUnit=YuQRtpLP10I&orgUnit=vWbkYPRmKyS&children=true";
-H "Accept:application/xml" -u admin:district -v</code></para>
- <para>You can get the response in <emphasis role="italic">xml</emphasis> and <emphasis
- role="italic">csv</emphasis> format. You can indicate which response format you prefer
+ <para>You can get the response in <emphasis role="italic">xml</emphasis> and <emphasis role="italic">csv</emphasis> format. You can indicate which response format you prefer
through the <emphasis role="italic">Accept</emphasis> HTTP header like in the example above.
- For xml you use <emphasis role="italic">application/xml</emphasis>; for csv you use <emphasis
- role="italic">application/csv</emphasis>.</para>
+ For xml you use <emphasis role="italic">application/xml</emphasis>; for csv you use <emphasis role="italic">application/csv</emphasis>.</para>
</section>
<section>
<title>Writing and reading messages</title>
@@ -1381,8 +1369,7 @@
delimited values. As an example, the following command would retrieve XML data for the SQL
view defined
above.<screen>curl "http://apps.dhis2.org/dev/api/sqlViews/dI68mLkP1wN/data.csv" -u admin:district -v</screen></para>
- <para>You can do simple filtering on the columns in the result set by appending <emphasis
- role="italic">criteria</emphasis> query parameters to the URL, using the column names and
+ <para>You can do simple filtering on the columns in the result set by appending <emphasis role="italic">criteria</emphasis> query parameters to the URL, using the column names and
filter values separated by columns as parameter values, on the following format:</para>
<screen>/data?criteria=col1:value1&criteria=col2:value2</screen>
<para>As an example, to filter the SQL view result set above to only return organisation units
@@ -1391,8 +1378,7 @@
</section>
<section>
<title>Analytics</title>
- <para>To access analytical, aggregated data in DHIS 2 you can work with the <emphasis
- role="italic">analytics</emphasis> resource. The analytics resource is powerful as it lets
+ <para>To access analytical, aggregated data in DHIS 2 you can work with the <emphasis role="italic">analytics</emphasis> resource. The analytics resource is powerful as it lets
you query and retrieve data aggregated along all available data dimensions. For instance, you
can ask the analytics resource to provide the aggregated data values for a set of data
elements, periods and organisation units. Also, you can retrieve the aggregated data for a
@@ -1403,8 +1389,7 @@
dimension. You can dynamically add dimensions through categories, data element group sets and
organisation unit group sets. The table below displays the available data dimensions in DHIS
2. Each data dimension has a corresponding <emphasis role="italic">dimension
- identifier</emphasis>, and each dimension can have a set of <emphasis role="italic"
- >dimension items</emphasis>:</para>
+ identifier</emphasis>, and each dimension can have a set of <emphasis role="italic">dimension items</emphasis>:</para>
<itemizedlist>
<listitem>
<table frame="all">
@@ -1467,8 +1452,7 @@
dimensions when designing analytics queries. You can get a complete list of dynamic dimensions
by visiting this URL in the Web API:</para>
<screen>api/dimensions</screen>
- <para>The base URL to the analytics resource is <emphasis role="italic"
- >api/analytics</emphasis>. To request specific dimensions and dimension items you can use a
+ <para>The base URL to the analytics resource is <emphasis role="italic">api/analytics</emphasis>. To request specific dimensions and dimension items you can use a
query string on the following format, where <emphasis role="italic">dim-id</emphasis> and
<emphasis role="italic">dim-item</emphasis> should be substituted with real values:</para>
<screen>api/analytics?dimension=dim-id:dim-item;dim-item&dimension=dim-id:dim-item;dim-item</screen>
@@ -1636,8 +1620,7 @@
<para>In order to have the analytics resource generate the data in the shape of a ready-made
table, you can provide the <emphasis role="italic">tableLayout</emphasis> parameter with
true as value. Instead of generating a plain, normalized data source, the analytics resource
- will now generate the data in table layout. You can use the <emphasis role="italic"
- >columns</emphasis> and <emphasis role="italic">rows</emphasis> parameters with dimension
+ will now generate the data in table layout. You can use the <emphasis role="italic">columns</emphasis> and <emphasis role="italic">rows</emphasis> parameters with dimension
identifiers separated by semi-colons as values to indicate which ones to use as table
columns and rows. The column and rows dimensions must be present as a data dimension in the
query (not a filter). Such a request can look like this:</para>
@@ -1673,8 +1656,7 @@
<para>As an example, to request an analytics response in XML format you can use the following
URL:</para>
<screen>api/analytics.xml?dimension=dx:fbfJHSPpUQD&dimension=pe:2012&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw</screen>
- <para>The analytics responses must be retrieved using the HTTP <emphasis role="italic"
- >GET</emphasis> method. This allows for direct linking to analytics responses from Web
+ <para>The analytics responses must be retrieved using the HTTP <emphasis role="italic">GET</emphasis> method. This allows for direct linking to analytics responses from Web
pages as well as other HTTP-enabled clients. To do functional testing we can use the cURL
library. By executing this command against the demo database you will get an analytics
response in JSON format:</para>
@@ -1740,18 +1722,12 @@
"width": 3
}
</screen>
- <para>The response represents a table of dimensional data. The <emphasis role="italic"
- >headers</emphasis> array gives an overview of which columns are included in the table and
+ <para>The response represents a table of dimensional data. The <emphasis role="italic">headers</emphasis> array gives an overview of which columns are included in the table and
what the columns contain. The <emphasis role="italic">column</emphasis> property shows the
column dimension identifier, or if the column contains measures, the word "Value". The
- <emphasis role="italic">meta</emphasis> property is <emphasis role="italic"
- >true</emphasis> if the column contains dimension items or <emphasis role="italic"
- >false</emphasis> if the column contains a measure (aggregated data values). The <emphasis
- role="italic">name</emphasis> property is similar to the column property, except it
- displays "value" in case the column contains a measure. The <emphasis role="italic"
- >type</emphasis> property indicates the Java class type of the column values.</para>
- <para>The <emphasis role="italic">height</emphasis> and <emphasis role="italic"
- >width</emphasis> properties indicate how many data columns and rows are contained in the
+ <emphasis role="italic">meta</emphasis> property is <emphasis role="italic">true</emphasis> if the column contains dimension items or <emphasis role="italic">false</emphasis> if the column contains a measure (aggregated data values). The <emphasis role="italic">name</emphasis> property is similar to the column property, except it
+ displays "value" in case the column contains a measure. The <emphasis role="italic">type</emphasis> property indicates the Java class type of the column values.</para>
+ <para>The <emphasis role="italic">height</emphasis> and <emphasis role="italic">width</emphasis> properties indicate how many data columns and rows are contained in the
response, respectively.</para>
<para>The <emphasis role="italic">metaData periods</emphasis> property contains a unique,
ordered list of the periods included in the response. The <emphasis role="italic">metaData
@@ -1830,8 +1806,7 @@
<title>FRED API</title>
<para>DHIS 2 from version 2.11 implements support for the current draft
of the FRED API version 1.0. The project defines itself as <quote>open standard for sharing and updating
- health facility data</quote>. The full specification, including representation format and basic usage, can be found at <ulink
- url="http://facilityregistry.org/";>http://facilityregistry.org/</ulink>.</para>
+ health facility data</quote>. The full specification, including representation format and basic usage, can be found at <ulink url="http://facilityregistry.org/";>http://facilityregistry.org/</ulink>.</para>
<para>Since version 1.0 is not finalized there are parts of the current specification that has not
been implemented as we found it not to be in a stable enough state. Most notably we do not
currently support sorting (we do however sort on name by default) and filtering of facilities.</para>
