1.9 Metadata create, read, update, delete, validate

While some of the web-api endpoints already contains support for CRUD (create, read, update, delete), from version 2.15 this is now supported on all endpoints. It should work as you expect, and the subsections will give more detailed information about create, update, and delete (read is already covered elsewhere, and have been supported for a long time).

1.9.1 Create / update parameters

The following query parameters are available for customizing your request.

Available Query Filters
Param Type Required Options (default first) Description
preheatCache boolean false true | false Turn cache-map preheating on/off. This is on by default, turning this off will make initial load time for importer much shorter (but will make the import itself slower). This is mostly used for cases where you have a small XML/JSON file you want to import, and don’t want to wait for cache-map preheating.
strategy enum false CREATE_AND_UPDATE | CREATE | UPDATE | DELETE Import strategy to use, see below for more information.
mergeMode enum false REPLACE, MERGE Strategy for merging of objects when doing updates. REPLACE will just overwrite the property with the new value provided, MERGE will only set the property if its not null (only if the property was provided).

1.9.2 Creating and updating objects

For creating new objects you will need to know the endpoint, the type format, and make sure that you have the required authorities. As an example , we will create and update an constant . To figure out the format, we can use the new schema endpoint for getting format description. So we will start with getting that info:

http://<<server>>/api/schemas/constant.json

From the output, you can see that the required authorities for create are F_CONSTANT_ADD, and the important properties are: name and value . From this we can create a JSON payload and save it as a file called constant.json:

{
  "name": "PI",
  "value": "3.14159265359"
}

The same content as an XML payload:

<constant name="PI" xmlns="http://dhis2.org/schema/dxf/2.0">
  <value>3.14159265359</value>
</constant>

We are now ready create the new constant by sending a POST request to the constants endpoint with the JSON payload using curl:

curl -d @constant.json "http://server/api/26/constants" -X POST
-H "Content-Type: application/json" -u user:password

A specific example of posting the constant to the demo server:

curl -d @constant.json "https://play.dhis2.org/api/26/constants" -X POST
-H "Content-Type: application/json" -u admin:district

If everything went well, you should see an output similar to:

The process will be exactly the same for updating, you make your changes to the JSON/XML payload, find out the ID of the constant, and then send a PUT request to the endpoint including ID:

1.9.3 Deleting objects

Deleting objects are very straight forward, you will need to know the ID and the endpoint of the type you want delete, let’s continue our example from the last section and use a constant . Let’s assume that the id is abc123 , then all you need to do is the send the DELETE request to the endpoint + id:

curl -X DELETE -u user:password
http://server/api/26/constants/ID

A successful delete should return HTTP status 204 (no content).

1.9.4 Adding and removing objects in collections

The collections resource lets you modify collections of objects.

1.9.4.1 Adding or removing single objects

In order to add or remove objects to or from a collection of objects you can use the following pattern:

/api/26/{collection-object}/{collection-object-id}/{collection-name}/{object-id}

You should use the POST method to add, and the DELETE method to remove an object. When there is a many-to-many relationship between objects, you must first determine which object owns the relationship. If it isn’t clear which object this is, try the call both ways to see which works.

The components of the pattern are:

  • collection object: The type of objects that owns the collection you want to modify.

  • collection object id: The identifier of the object that owns the collection you want to modify.

  • collection name: The name of the collection you want to modify.

  • object id: The identifier of the object you want to add or remove from the collection.

As an example, in order to remove a data element with identifier IDB from a data element group with identifier IDA you can do a DELETE request:

DELETE /api/26/dataElementGroups/IDA/dataElements/IDB

To add a category option with identifier IDB to a category with identifier IDA you can do a POST request:

POST /api/26/categories/IDA/categoryOptions/IDB

1.9.4.2 Adding or removing multiple objects

You can add or remove multiple objects from a collection in one request with a payload like this:

{
  "identifiableObjects": [
    { "id": "IDA" },
    { "id": "IDB" },
    { "id": "IDC" }
  ]
}

Using this payload you can add, replace or delete items:

Adding Items:

POST /api/26/categories/IDA/categoryOptions

Replacing Items:

PUT /api/26/categories/IDA/categoryOptions

Delete Items:

DELETE /api/26/categories/IDA/categoryOptions

1.9.4.3 Adding and removing objects in a single request

You can both add and remove objects from a collection in a single POST request with the following type of payload:

POST /api/26/categories/IDA/categoryOptions

{
  "additions": [
    { "id": "IDA" },
    { "id": "IDB" },
    { "id": "IDC" }
  ],
  "deletions": [
    { "id": "IDD" },
    { "id": "IDE" },
    { "id": "IDF" }
  ]
}

1.9.5 Validating payloads

System wide validation of metadata payloads are enabled from 2.19 release, this means that create/update operations on the web-api endpoints will be checked for valid payload before allowed changes to be made, to find out what validations are in place for a endpoint, please have a look at the /api/schemas endpoint, i.e. to figure out which constraints a data element have, you would go to /api/schemas/dataElement.

You can also validate your payload manually by sending it to the proper schema endpoint. If you wanted to validate the constant from the create section before, you would send it like this:

POST /api/schemas/constant
{ payload }

A simple (non-validating) example would be:

curl -X POST -d "{\"name\": \"some name\"}" -H "Content-Type: application/json"
-u admin:district https://play.dhis2.org/dev/api/schemas/dataElement

Which would yield the result:

[
   {
      "message" : "Required property missing.",
      "property" : "type"
   },
   {
      "property" : "aggregationOperator",
      "message" : "Required property missing."
   },
   {
      "property" : "domainType",
      "message" : "Required property missing."
   },
   {
      "property" : "shortName",
      "message" : "Required property missing."
   }
]

1.9.6 Partial updates

For cases where you don’t want or need to update all properties on a object (which means downloading a potentially huge payload, change one property, then upload again) we now support partial update, for one or more properties.

The payload for doing partial updates are the same as when you are doing a full update, the only difference is that you only include the properties you want to update, i.e.:

{ // file.json
  "name": "Updated Name",
  "zeroIsSignificant": true
}

curl -X PATCH -d @file.json -H "Content-Type: application/json"
-u admin:district https://play.dhis2.org/dev/api/26/dataElements/fbfJHSPpUQD