1.78 Data store

Using the dataStore resource, developers can store arbitrary data for their apps. Access to a datastore’s key is based on its sharing settings. By default all keys created are publicly accessible (read and write). Additionally, access to a datastore’s namespace is limited to the user’s access to the corresponding app, if the app has reserved the namespace. For example a user with access to the “sampleApp” application will also be able to use the sampleApp namespace in the datastore. If a namespace is not reserved, no specific access is required to use it.

/api/26/dataStore

1.78.1 Data store structure

Data store entries consist of a namespace, key and value. The combination of namespace and key is unique. The value data type is JSON.

Data store structure
Item Description Data type
Namespace Namespace for organization of entries. String
Key Key for identification of values. String
Value Value holding the information for the entry. JSON
Encrypted Indicates whether the value of the given key should be encrypted Boolean

1.78.2 Get keys and namespaces

For a list of all existing namespaces:

GET /api/26/dataStore

Example curl request for listing:

curl "play.dhis2.org/demo/api/26/dataStore" -X GET -u admin:district -v

Example response:

[
    "foo",
    "bar"
]

For a list of all keys in a namespace:

GET /api/26/dataStore/<namespace>

Example curl request for listing:

curl "play.dhis2.org/demo/api/26/dataStore/foo" -X GET -u admin:district -v

Example response:

[
    "key_1",
    "key_2"
]

To retrieve a value for an existing key from a namespace:

GET /api/26/dataStore/<namespace>/<key>

Example curl request for retrieval:

curl "play.dhis2.org/demo/api/26/dataStore/foo/key_1" -X GET -u admin:district -v

Example response:

{
    "foo":"bar"
}

To retrieve meta-data for an existing key from a namespace:

GET /api/26/dataStore/<namespace>/<key>/metaData

Example curl request for retrieval:

curl "play.dhis2.org/demo/api/26/dataStore/foo/key_1/metaData" -X GET -u admin:district -v

Example response:

{
    "created": "...",
    "user": {...},
    "namespace": "foo",
    "key": "key_1"
}

1.78.3 Create values

To create a new key and value for a namespace:

POST /api/26/dataStore/<namespace>/<key>

Example curl request for create, assuming a valid json payload:

curl "https://play.dhis2.org/demo/api/26/dataStore/foo/key_1" -X POST
  -H "Content-Type: application/json" -d "{\"foo\":\"bar\"}" -u admin:district -v

Example response:

{
    "httpStatus": "OK",
    "httpStatusCode": 201,
    "status": "OK",
    "message": "Key 'key_1' created."
}

If you require the data you store to be encrypted (for example user credentials or similar) you can append a query to the url like this:

GET /api/26/dataStore/<namespace>/<key>?encrypt=true

1.78.4 Update values

To update a key that exists in a namespace:

PUT /api/26/dataStore/<namespace>/<key>

Example curl request for update, assuming valid JSON payload:

curl "https://play.dhis2.org/demo/api/26/dataStore/foo/key_1" -X PUT -d "[1, 2, 3]"
  -H "Content-Type: application/json" -u admin:district -v

Example response:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "message": "Key 'key_1' updated."
}

1.78.5 Delete keys

To delete an existing key from a namespace:

DELETE /api/26/dataStore/<namespace>/<key>

Example curl request for delete:

curl "play.dhis2.org/demo/api/26/dataStore/foo/key_1" -X DELETE -u admin:district -v

Example response:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "message": "Key 'key_1' deleted from namespace 'foo'."
}

To delete all keys in a namespace:

DELETE /api/26/dataStore/<namespace>

Example curl request for delete:

curl "play.dhis2.org/demo/api/26/dataStore/foo" -X DELETE -u admin:district -v

Example response:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "message": "Namespace 'foo' deleted."
}

1.78.6 Sharing datastore keys

Sharing of datastore keys follows the same principle as for other metadata sharing (see Sharing ).

To get sharing settings for a specific datastore key:

GET /api/31/sharing?type=dataStore&id=<uid>

To modify sharing settings for a specific datastore key:

POST /api/31/sharing?type=dataStore&id=<uid>

with the following request:

{
"object": {
    "publicAccess": "rw------",
    "externalAccess": false,
    "user": {},
    "userAccesses": [],
    "userGroupAccesses": [
        {
            "id": "hj0nnsVsPLU",
            "access": "rw------"
        },
        {
            "id": "qMjBflJMOfB",
            "access": "r-------"
        }
    ]
}
}