dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #25362
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 829: Web api, replaced all references to UID with identifier. There is only one identifier from a clie...
------------------------------------------------------------
revno: 829
committer: Lars Helge Øverland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Thu 2013-10-10 19:18:09 +0200
message:
Web api, replaced all references to UID with identifier. There is only one identifier from a client perspective.
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-10-04 12:37:21 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2013-10-10 17:18:09 +0000
@@ -468,18 +468,18 @@
] }
]
}</screen>
- <para>(From 2.13) As part of the import summary you will also get the UID <emphasis
+ <para>(From 2.13) As part of the import summary you will also get the identifier <emphasis
role="italic">reference</emphasis> to the event you just sent, together with a <emphasis
role="italic">href</emphasis> 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.
+ payload is the same, but the URL you are posting to must add the identifier 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
+ send a DELETE request with a identifier reference to the server you are
using.<screen>curl -X DELETE "localhost:8080/api/events/Abcas12322" -u admin:district -v</screen></para>
<para><emphasis role="bold">Get</emphasis>: To get an existing event you can issue a GET request
- including the UID reference like
+ including the identifier like
this:<screen>curl "localhost:8080/api/events/Abcas12322" -H "Content-Type:application/xml" -u admin:district -v</screen></para>
<para>The table below describes the meaning of each element. Most elements should be fairly
self-explanatory.</para>
@@ -512,14 +512,14 @@
<entry>string</entry>
<entry>true</entry>
<entry/>
- <entry>UID of the single event with no registration program</entry>
+ <entry>Identifier of the single event with no registration program</entry>
</row>
<row>
<entry>organisationUnitId</entry>
<entry>string</entry>
<entry>true</entry>
<entry/>
- <entry>UID of the organisation unit where the event took place</entry>
+ <entry>Identifier of the organisation unit where the event took place</entry>
</row>
<row>
<entry>eventDate</entry>
@@ -556,7 +556,7 @@
<entry>string</entry>
<entry>true</entry>
<entry/>
- <entry>UID of data element</entry>
+ <entry>Identifier of data element</entry>
</row>
<row>
<entry>value</entry>
@@ -604,8 +604,10 @@
</ns:DataSet>
</CrossSectionalData>]]></screen>
- <para>One thing to note is that the SDMX-HD metadata for dataelements, orgunits and datasets are identified using <emphasis>codes</emphasis> rather than <emphasis>uids</emphasis>.
- Assuming these coded datasets are present in the DHIS2 server then this can be posted, for example using the curl command below.</para>
+ <para>One thing to note is that the SDMX-HD metadata for dataelements, orgunits and datasets are
+ identified using <emphasis>codes</emphasis> rather than <emphasis>identifiers</emphasis>.
+ Assuming these coded datasets are present in the DHIS2 server then this can be posted, for
+ example using the curl command below.</para>
<para><code>curl -d @sdmxdatavalueset.xml "http://{server base url}/api/dataValueSets" -H "Content-Type:application/sdmx+xml" -u admin:district -v</code></para>
</section>
<section>
@@ -646,12 +648,12 @@
<tbody>
<row>
<entry>dataElementIdScheme</entry>
- <entry>uid | name | code</entry>
+ <entry>id | name | code</entry>
<entry>Which property on the data element object to reference from the XML attribute</entry>
</row>
<row>
<entry>orgUnitIdScheme</entry>
- <entry>uid | name | code</entry>
+ <entry>id | name | code</entry>
<entry>Which property on the org unit object to reference from the XML attribute</entry>
</row>
<row>
@@ -675,7 +677,13 @@
orgUnitIdScheme="name" dryRun="true" importStrategy="new">
..
</dataValueSet></screen>
- <para>Regarding the id schemes, by default the identifiers used in the XML messages refer to the DHIS stable object identifiers. In certain interoperability situations we might experience that the external system decides the identifiers of the objects. In that case we can use the <emphasis role="italic">code</emphasis> property of the organisation unit and data element objects to set fixed identifiers dictated by the other system. When importing data values we hence need to reference the code property instead of the uid property, and can do so using the dataElementIScheme and orgUnitIdScheme paramaters.</para>
+ <para>Regarding the id schemes, by default the identifiers used in the XML messages refer to the
+ DHIS stable object identifiers. In certain interoperability situations we might experience
+ that the external system decides the identifiers of the objects. In that case we can use the
+ <emphasis role="italic">code</emphasis> property of the organisation unit and data element
+ objects to set fixed identifiers dictated by the other system. When importing data values we
+ hence need to reference the code property instead of the identfier property, and can do so
+ using the dataElementIScheme and orgUnitIdScheme paramaters.</para>
</section>
<section>
<title>Reading data values</title>
@@ -1785,7 +1793,7 @@
<screen>api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2012&dimension=ou:LEVEL-3</screen>
<screen>api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2012&dimension=ou:LEVEL-3;LEVEL-4;O6uvpzGd5pu;lc3eMKXaEf</screen>
<para>When selecting organisation units you can also select all organisation units in an
- organisation unit group to be included as dimension items using the OU_GROUP-<uid> syntax.
+ organisation unit group to be included as dimension items using the OU_GROUP-<id> syntax.
The organisation units in the groups can optionally be constrained by any number of boundary
organisation units. Both the level and the group items can be repeated any number of
times:</para>
@@ -2140,18 +2148,18 @@
<tbody>
<row>
<entry>Data elements</entry>
- <entry><uid></entry>
+ <entry><id></entry>
<entry>Data element identifiers</entry>
</row>
<row>
<entry>Person attributes</entry>
- <entry><uid>, GENDER, ISDEAD</entry>
+ <entry><id>, GENDER, ISDEAD</entry>
<entry>Person attribute identifiers and the fixed person attributes GENDER and
ISDEAD</entry>
</row>
<row>
<entry>Person identifiers</entry>
- <entry><uid></entry>
+ <entry><id></entry>
<entry>Person identifier identifiers</entry>
</row>
<row>
@@ -2265,16 +2273,16 @@
<row>
<entry>asc</entry>
<entry>No</entry>
- <entry>Dimensions to be sorted ascending, can reference executiondate or any
+ <entry>Dimensions to be sorted ascending, can reference event date or any
items.</entry>
- <entry>executiondate | item identifier</entry>
+ <entry>EVENTDATE | item identifier</entry>
</row>
<row>
<entry>desc</entry>
<entry>No</entry>
- <entry>Dimensions to be sorted descending, can reference executiondate or any
+ <entry>Dimensions to be sorted descending, can reference event date or any
items.</entry>
- <entry>executiondate | item identifier</entry>
+ <entry>EVENTDATE | item identifier</entry>
</row>
<row>
<entry>page</entry>
@@ -2345,10 +2353,10 @@
<para>Fixed person attributes can be specified as dimensions as well. Currently the GENDER and
ISDEAD attributes are suppored and can be included and filtered on like this:</para>
<screen>api/analytics/events/query/IpHINAT79UW?stage=A03MvHHogjR&startDate=2012-03-01&endDate=2012-12-31&dimension=ou:O6uvpzGd5pu&dimension=UXz7xuGCEhU:GT:2000&dimension=ISDEAD&dimension=GENDER:EQ:F</screen>
- <para>Sorting can be applied to the query for the "executiondate" of the event and any
- dimensions. To sort descending on the executiondate and ascending on the "Age" data element
- dimension you can use:</para>
- <screen>api/analytics/events/query/eBAyeGv0exc?startDate=2012-01-01&endDate=2012-10-31&dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&desc=executiondate&asc=qrur9Dvnyt5</screen>
+ <para>Sorting can be applied to the query for the event date of the event and any dimensions.
+ To sort descending on the event date and ascending on the "Age" data element dimension you
+ can use:</para>
+ <screen>api/analytics/events/query/eBAyeGv0exc?startDate=2012-01-01&endDate=2012-10-31&dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&desc=EVENTDATE&asc=qrur9Dvnyt5</screen>
<para>Paging can be applied to the query by specifying the page number and the page size
parameters. If page number is specified but page size is not, a page size of 50 will be
used. If page size is specified but page number is not, a page number of 1 will be used. To
@@ -2454,8 +2462,8 @@
"meta": false
},
{
- "name": "executiondate",
- "column": "Execution date",
+ "name": "eventdate",
+ "column": "Event date",
"type": "java.lang.String",
"hidden": false,
"meta": false
@@ -2519,7 +2527,7 @@
}</screen>
<para>The <emphasis role="italic">headers</emphasis> section of the response describes the
content of the query result. The event unique identifier, the program stage identifier,
- the execution date, the organisation unit name, the organisation unit code and the
+ the event date, the organisation unit name, the organisation unit code and the
organisation unit identifier appear as the first six dimensions in the response and will
always be present. Next comes the data elements, person attributes and person identifiers
which were specified as dimensions in the request, in this case the "Gender" and "Age"
@@ -2685,12 +2693,13 @@
<para>The system resource provides you with convenient information and functions. The system
resource can be found at <emphasis role="italic">/api/system</emphasis>. </para>
<section>
- <title>Generate UIDs</title>
- <para>To genereate valid, random UIDs you can do a GET request to this resource:</para>
- <screen>http://<server-url>/api/system/uid?n=3</screen>
+ <title>Generate identifiers</title>
+ <para>To genereate valid, random DHIS 2 identifiers you can do a GET request to this
+ resource:</para>
+ <screen>http://<server-url>/api/system/id?n=3</screen>
<para>The <emphasis role="italic">n</emphasis> query parameter is optional and indicates how
- many UIDs you want to be returned with the response. The default is to return one UID. The
- response will contain a JSON array similar to this:</para>
+ many identifiers you want to be returned with the response. The default is to return one
+ identifier. The response will contain a JSON array similar to this:</para>
<screen>[
"Y0moqFplrX4",
"WI0VHXuWQuV",
@@ -2835,7 +2844,7 @@
<para>For creating a new person in the system, you will be working with the <emphasis
role="italic">persons</emphasis> resource. An template payload can be seen
below:<screen>{
- "orgUnit": "Uid of the organisationUnit",
+ "orgUnit": "Identifier of the organisationUnit",
"name": "Name of Person",
"gender": "MALE / FEMALE / TRANSGENDER",
"dateOfBirth": {
@@ -2848,15 +2857,15 @@
},
"relationships": [
- { "type": "Uid of the relationshipType", "person": "LhsYtC2Hmpi" }
+ { "type": "Identifier of the relationshipType", "person": "LhsYtC2Hmpi" }
],
"identifiers": [
- { "type": "Uid of the personIdentifier", "value": "uuid-13" }
+ { "type": "Identifier of the personIdentifier", "value": "123" }
],
"attributes": [
- { "type": "Uid of the personAttribute", "value": "This is my new address" }
+ { "type": "Identifier of the personAttribute", "value": "This is my new address" }
]
}</screen></para>
<para>For getting the identifiers for <emphasis role="italic">relationship</emphasis>,
@@ -2869,8 +2878,8 @@
<title>Updating a person</title>
<para>For updating a person, the payload is the same as in the previous section. The only
different is that you must use the HTTP method <emphasis role="bold">PUT</emphasis> when
- sending the payload, you will also need to add the person identifier (UID) to the <emphasis
- role="italic">persons</emphasis> resource (i.e. /api/persons/UID).</para>
+ sending the payload, you will also need to add the person identifier to the <emphasis
+ role="italic">persons</emphasis> resource (i.e. /api/persons/<id>).</para>
</section>
<section>
<title>Deleting a person</title>
@@ -2883,20 +2892,20 @@
<para>There are several parameter available on the <emphasis role="italic">persons</emphasis>
resource for querying for persons, <emphasis role="italic">orgUnit</emphasis> paramter is
always required (unless querying for identifiers, please see below).</para>
- <para><emphasis role="bold">Query for
- orgUnit:</emphasis><screen>GET /api/persons?orgUnit=OU_UID</screen></para>
- <para><emphasis role="bold">Query for
- orgUnit/nameLike:</emphasis><screen>GET /api/persons?orgUnit=OU_UID&nameLike=sen</screen></para>
- <para><emphasis role="bold">Query for
- orgUnit/program:</emphasis><screen>GET /api/persons?orgUnit=OU_UID&program=PROGRAM_UID</screen></para>
- <para><emphasis role="bold">Query for
- orgUnit/program/gender:</emphasis><screen>GET /api/persons?orgUnit=OU_UID&program=PROGRAM_UID&gender=MALE/FEMALE/TRANSGENDER</screen></para>
- <para><emphasis role="bold">Query for
- orgUnit/gender:</emphasis><screen>GET /api/persons?orgUnit=OU_UID&gender=MALE/FEMALE/TRANSGENDER</screen></para>
+ <para><emphasis role="bold">Query for org
+ unit:</emphasis><screen>GET /api/persons?orgUnit=<orgunit-id></screen></para>
+ <para><emphasis role="bold">Query for org
+ unit/nameLike:</emphasis><screen>GET /api/persons?orgUnit=<orgunit-id>&nameLike=sen</screen></para>
+ <para><emphasis role="bold">Query for org
+ unit/program:</emphasis><screen>GET /api/persons?orgUnit=<orgunit-id>&program=<program-id></screen></para>
+ <para><emphasis role="bold">Query for org
+ unit/program/gender:</emphasis><screen>GET /api/persons?orgUnit=<orgunit-id>&program=<program-id>&gender=MALE/FEMALE/TRANSGENDER</screen></para>
+ <para><emphasis role="bold">Query for org
+ unit/gender:</emphasis><screen>GET /api/persons?orgUnit=<orgunit-id>&gender=MALE/FEMALE/TRANSGENDER</screen></para>
<para><emphasis role="bold">Query for system
identifier:</emphasis><screen>GET /api/persons?identifier=SYSTEM_ID</screen></para>
<para><emphasis role="bold">Query for specific identifier
- type:</emphasis><screen>GET /api/persons?identifierType=ID_TYPE_UID&identifier=ID_VALUE</screen></para>
+ type:</emphasis><screen>GET /api/persons?identifierType=<id-type-id>&identifier=<person-id></screen></para>
</section>
<section>
<title>Enrolling a person into a program</title>
@@ -2913,8 +2922,8 @@
<para>For cancelling or completing an enrollment, you can send a <emphasis role="bold"
>PUT</emphasis> request to the <emphasis role="italic">enrollments</emphasis> resource,
including the identifier and the action you want to perform. For
- cancelling:<screen>PUT /api/enrollments/UID/cancelled</screen></para>
- <para>For completing:<screen>PUT /api/enrollments/UID/completed</screen></para>
+ cancelling:<screen>PUT /api/enrollments/<enrollment-id>/cancelled</screen></para>
+ <para>For completing:<screen>PUT /api/enrollments/<enrollment-id>/completed</screen></para>
</section>
</section>
<section>
@@ -2930,17 +2939,17 @@
<para>This section will give some simple examples of using the API.</para>
<para>Get all facilities:</para>
<screen>curl -u username:password -X GET http://<server-url>/api-fred/v1/facilities.json</screen>
- <para>Get a specific facility based on either UID or UUID:</para>
- <screen>curl -u username:password -X GET http://<server-url>/api-fred/v1/facilities/UID.json
-curl -u username:password -X GET http://<server-url>/api-fred/v1/facilities/UUID.json</screen>
+ <para>Get a specific facility based on either identifier or UUID:</para>
+ <screen>curl -u username:password -X GET http://<server-url>/api-fred/v1/facilities/<id>.json
+curl -u username:password -X GET http://<server-url>/api-fred/v1/facilities/<uuid>.json</screen>
<para>Create a new facility:</para>
<screen>curl -u username:password -X POST -d @new_facility.json
-H "Content-Type: application/json" http://<server-url>/api-fred/v1/facilities.json</screen>
<para>Update a facility:</para>
<screen>curl -u username:password -X POST -d @updated_facility.json
- -H "Content-Type: application/json" http://<server-url>/api-fred/v1/facilities/UID.json</screen>
+ -H "Content-Type: application/json" http://<server-url>/api-fred/v1/facilities/<id>.json</screen>
<screen>
curl -u username:password -X POST -d @updated_facility.json
- -H "Content-Type: application/json" http://<server-url>/api-fred/v1/facilities/UUID.json</screen>
+ -H "Content-Type: application/json" http://<server-url>/api-fred/v1/facilities/<uuid>.json</screen>
</section>
</chapter>
