Datastore

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/dataStore

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.

Get keys and namespaces#

For a list of all existing namespaces:

GET /api/dataStore

Example curl request for listing:

curl "dev.hrhis.dhis2udsm.org/demo/api/dataStore" -u admin:district

Example response:

[
  "foo",
  "bar"
]

For a list of all keys in a namespace:

GET /api/dataStore/<namespace>

Example curl request for listing:

curl "dev.hrhis.dhis2udsm.org/demo/api/dataStore/foo" -u admin:district

Example response:

[
  "key_1",
  "key_2"
]

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

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

Example curl request for retrieval:

curl "dev.hrhis.dhis2udsm.org/demo/api/dataStore/foo/key_1"-u admin:district

Example response:

{
  "foo":"bar"
}

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

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

Example curl request for retrieval:

curl "dev.hrhis.dhis2udsm.org/demo/api/dataStore/foo/key_1/metaData" -u admin:district

Example response:

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

Create values#

To create a new key and value for a namespace:

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

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

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

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/dataStore/<namespace>/<key>?encrypt=true

Update values#

To update a key that exists in a namespace:

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

Example curl request for update, assuming valid JSON payload:

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

Example response:

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

Delete keys#

To delete an existing key from a namespace:

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

Example curl request for delete:

curl "dev.hrhis.dhis2udsm.org/demo/api/dataStore/foo/key_1" -X DELETE -u admin:district

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/dataStore/<namespace>

Example curl request for delete:

curl "dev.hrhis.dhis2udsm.org/demo/api/dataStore/foo" -X DELETE -u admin:district

Example response:

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

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/sharing?type=dataStore&id=<uid>

To modify sharing settings for a specific datastore key:

POST /api/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-------"
            }
        ]
    }
}

User data store#

In addition to the dataStore which is shared between all users of the system, a user-based data store is also available. Data stored to the userDataStore is associated with individual users, so that each user can have different data on the same namespace and key combination. All calls against the userDataStore will be associated with the logged in user. This means one can only see, change, remove and add values associated with the currently logged in user.

/api/userDataStore

User data store structure#

userDataStore consists of a user, a namespace, keys and associated values. The combination of user, namespace and key is unique.

Get namespaces#

Returns an array of all existing namespaces

GET /api/userDataStore

Example request:

curl -H "Content-Type: application/json" -u admin:district "dev.hrhis.dhis2udsm.org/api/userDataStore"

[
  "foo",
  "bar"
]

Get keys#

Returns an array of all existing keys in a given namespace

GET /api/userDataStore/<namespace>

Example request:

curl -H "Content-Type: application/json" -u admin:district "dev.hrhis.dhis2udsm.org/api/userDataStore/foo"

[
  "key_1",
  "key_2"
]

Get values#

Returns the value for a given namespace and key

GET /api/userDataStore/<namespace>/<key>

Example request:

curl -H "Content-Type: application/json" -u admin:district "dev.hrhis.dhis2udsm.org/api/userDataStore/foo/bar"

{
  "some": "value"
}

Create value#

Adds a new value to a given key in a given namespace.

POST /api/userDataStore/<namespace>/<key>

Example request:

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "dev.hrhis.dhis2udsm.org/api/userDataStore/foo/bar"

{
  "httpStatus": "Created",
  "httpStatusCode": 201,
  "status": "OK",
  "message": "Key 'bar' in namespace 'foo' created."
}

If you require the value to be encrypted (For example user credentials and such) you can append a query to the url like this:

GET /api/userDataStore/<namespace>/<key>?encrypt=true

Update values#

Updates an existing value

PUT /api/userDataStore/<namespace>/<key>

Example request:

curl -X PUT -H "Content-Type: application/json" -u admin:district -d "['new value']"
  "dev.hrhis.dhis2udsm.org/api/userDataStore/foo/bar"

{
  "httpStatus":"Created",
  "httpStatusCode":201,
  "status":"OK",
  "message":"Key 'bar' in namespace 'foo' updated."
}

Delete key#

Delete a key

DELETE /api/userDataStore/<namespace>/<key>

Example request:

curl -X DELETE -u admin:district "dev.hrhis.dhis2udsm.org/api/userDataStore/foo/bar"

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

Delete namespace#

Delete all keys in the given namespace

DELETE /api/userDataStore/<namespace>

Example request:

curl -X DELETE -u admin:district "dev.hrhis.dhis2udsm.org/api/userDataStore/foo"

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