4 Management API

The Management API is used for creating new datasets and managing dataset permissions via the use of keys.

API methods are documented and can be tested using the web tools provided at:

https://<api-factory location>/management/

Before testing the API methods, use the Authorize button at the top right of the page, logging in using the username and password mentioned in Step 1 of the installation instructions.

Datasets

Create a dataset

New datasets can be created by using the PUT method against the following URL:

https://<api-factory location>/management/datasets/<dataset-uuid>?key=<key>

Use Basic Authentication to authenticate the request, with a username and password that has appropriate rights for creating collections, users and roles within your database.

Note that the key specified in the URL query parameter will be assigned as the primary access key for this dataset and will be granted both read and write privileges.

Example

curl -X PUT "https://api.mksmart.org/data/management/datasets/59e8d315-d57e-4b1e-83a2-b144d49b36d5?key=3f81d975-c2e1-4f12-a999-b63a76092a80" -H "accept: */*" -H "Authorization: Basic YQRtaW412cJWzc3dvvcmQxMjM="

Retrieve a list of datasets

A list of datasets can be retrieved by making a HTTP GET request on the following URL, using the same authenitication method described above:

https://<api-factory location>/management/datasets

Example

curl -X GET "https://api.mksmart.org/data/management/datasets" -H "accept: */*" -H "Authorization: Basic YQRtaW412cJWzc3dvvcmQxMjM="

Retrieve a single dataset

Performing a HTTP GET request on the following URL will report the number of documents that the dataset contains.

https://<api-factory location>/management/datasets/<dataset-uuid>

Example

curl -X GET "https://api.mksmart.org/data/management/datasets/59e8d315-d57e-4b1e-83a2-b144d49b36d5" -H "accept: */*" -H "Authorization: Basic YQRtaW412cJWzc3dvvcmQxMjM="

Permissions

Setting permissions

Permissions can be assigned to datasets using the permissions API method. A HTTP POST call to this method uses the following URL to set permissions:

https://\<api-factory location\>/management/permissions/\<dataset-uuid\>?key=\<key\>&read=[1/0]&write=[1/0]

Note the use of the read and write URL parameters which should be set to 1 or 0 to control dataset permissions accordingly. If an existing key is used, the permissions for that key will be updated accordingly, else a new key will be created.

This API method is also called automatically, on creation of all datasets, with the supplied master key which is granted full read and write access to the dataset.

Example

curl -X POST "https://api.mksmart.org/data/management/permissions/3f81d975-c2e1-4f12-a999-b63a76092a80?dataset-uuid=59e8d315-d57e-4b1e-83a2-b144d49b36d5&read=1&write=0" -H "accept: */*" -H "Authorization: Basic YQRtaW412cJWzc3dvvcmQxMjM="

Retrieving permissions

A summary of existing permissions can be obtained by performing a HTTP GET request on the Management API's permissions method. If no key ID is suppled, all permissions are retrieved. If a key ID is supplied, only for the permissions for that key are retrieved.

Examples

All permissions:

curl -X GET "https://api.mksmart.org/data/management/permissions" -H "accept: */*" -H "Authorization: Basic YQRtaW412cJWzc3dvvcmQxMjM="

Permissions for a single dataset:

curl -X GET "https://api.mksmart.org/data/management/permissions/key-id-12345" -H "accept: */*" -H "Authorization: Basic YQRtaW412cJWzc3dvvcmQxMjM="