Data storage explained

The Data Storage intended to be a light-weight database to store structured data in searchable form. It is not a full-blown relational database, but it serves most use cases for cloud and mobile-first applications. It has built-in access control.

Basics

The Data Storage is an API for storing JSON based data on the service. A single Data Storage has its own:

Access Control section. Access can be given for administration tasks, data read, and data write operations. Access can be given to individual Management API Clients or Users. Access given currently applies to all data attributes in the Data section. I.e. the resolution of control is coarse. For different use cases, create separate data storages.
Owner. The Data Storage may be deleted for example after an User owner is deleted. The Owner does not automatically, nor necessarily have full access to the Data Storage. The owner can be a Management API Client or an User. I.e. ownership does not give permissions, and it is separate from access control. It is good practise to have proper and correct data storage owners.
Data section. Accessible only to those who have data read or data write access via the access control section.

A new Data Storage can be created with the creation endpoint. Using it requires a special permission: DATA_STORAGE_CREATE.

Data section

The data section is a JSON object. It can contain any valid JSON content under unlimited number of sub-keys.

Data read and write operations

Data can be added either by replacing the whole data section, or by replacing single keys in the data section.

Data can be read by downloading the whole data section as one JSON document, or by downloading individual key values.

Limitations

The API is limited by the backend storage solution in the following ways:

Maximum Data Storage size is currently 16 MB for single datastorage. This includes all metadata. After this limitation has been reached, trying to add data will not succeed.
Number of Data Storages is currently not limited.
Data keys can contain dot ('.') characters, but they cannot be used in search filters. Therefore it is not recommended to use dots in any keys.

Shall the size limitation be observed, some re-factoring is needed. Splitting data is recommended well before maximum size for best performance.

Remarks on stored data

It is not recommended to store binary data in Data Storage. However, small (couple of kilobytes) base64-encoded binaries are ok. If your needs are different, you need to experiment.
It is possible to store pre-encrypted data. It is normally stored in base64-encoded form.

Data Storage Configurations

DataStorage object configurations:

meta
- created (string) – Read only. Example: 2017-10-20T07:17:17.606Z
- lastModified (string) Read only. – Example: 2017-10-20T07:17:17.606Z
- location (string) – Read only. Resource's location URI
id (string) – unique ID
name (string) – human readable name of the data storage
description (string) – additional notes
size (integer) – size of storage in bytes
ownerId (string) – ID of owner user account. Storage may be removed automatically if owner is removed from the system.
adminAccess – list of IDs of user / user group / management api client which can write data.
readAccess – list of IDs of user / user group / management api client which can read data.
writeAccess – list of IDs of user / user group / management api client which can write data.

Examples

Example value

{
  "id": "string",
  "meta": {
    "created": "2017-10-20T07:17:17.606Z",
    "lastModified": "2017-10-20T07:17:17.606Z",
    "location": "https://example.com/resource/112233"
  },
  "name": "string",
  "description": "string",
  "size": 0,
  "ownerId": "string",
  "adminAccess": [
    "string"
  ],
  "readAccess": [
    "string"
  ],
  "writeAccess": [
    "string"
  ]
}

Search

If you have access to multiple data storages, it may be necessary to search for one that matches a filter. The endpoint which is used to list data storages supports using 'datafilter' parameter. If it is used with a valid filter string, the endpoint will return only data storages which match the filter. The filter is given in SCIM compatible format (see RFC-7644). Complex filters are not supported.

Time stamps filtering is not yet implemented on some servers. For the time stamp querying ISO_INSTANT Date Format must be used. The meta-object doesn't support filtering, but most of the objects have "createDate" and "lastModifiedDate" properties.

Examples:

filter=username eq "john" (username value must be identical for a match)

filter=name.firstName ne "john" (first name value must not be identical for a match)

filter=address.streetAddress co "katu" (address's street name must contain "katu")

filter=group sw "gr" (filter groups that start with "gr")

filter=id pr (find all objects that has non-empty or non-null ID value)

Time stamp filtering examples:

filter=createDate ge "2016-10-20T07:17:17.606Z" (find all objects that were created after defined date)

See the RFC-7644 for more comprehensive examples.

OpenAPI Endpoints

The Management API end-points for Data Storage are as follows:

As the API subject for improvements, the above may not be up to date.

List all accessible data storages

API end-point: GET /api/rest/v1/datastorage

OAuth requirements: https://oneportal.trivore.com/scope/datastorage.readonly scope

Get the list of the objects that contain Data Storage configurations (doesn't contain the data).

Responses:

200 when the list of data storages was successfully found
400 in case of filter parser error

Query parameters:

startIndex pagination start index (0 - based)
count pagination page size (max 500)
dsfilter data storage configuration filter.
- ```
dsfilter=ownerId eq exampleID
```

datafilter data filter.

datafilter=objectKey.subKey eq exampleValue

datafilter=created ge 2017-10-20T07:17:17.606Z

Add new data storage

API end-point: POST /api/rest/v1/datastorage

Management API requirements : DATA_STORAGE_CREATE permission

OAuth requirements: https://oneportal.trivore.com/scope/datastorage.admin scope

No query parameters are required. The request body should contain the data storage configurations.

Responses:

201 when the data storage was successfully created
409 in case of data storage ID or name conflict

Examples:

Python requests example

import requests

data_storage = {
	'id' 			: 'exampleID',
	'name' 			: 'exampleName',
	'description' 	: 'onePortal example data storage'
}

requests.post('https://example.uri.com/api/rest/v1/datastorage',
			  json=data_storage,
			  auth=(client_id, client_secret))

Get datastorage settings

API end-point: GET /api/rest/v1/datastorage/{dsID}

OAuth requirements: https://oneportal.trivore.com/scope/datastorage.readonly scope

Find the data storage configurations by its ID.

Responses:

200 when the data storage was successfully found
404 in case the data storage ID was not found or is not accessible

Update datastorage configurations

API end-point: PUT /api/rest/v1/datastorage/{dsID}

OAuth requirements: https://oneportal.trivore.com/scope/datastorage.admin scope

Responses:

200 when the data storage was successfully updated
409 in case of data storage ID or name conflict

Examples:

Python requests example

import requests

data_storage = {
	'id' 			: 'exampleID',
	'name' 			: 'exampleName',
	'description' 	: 'onePortal example data storage'
}

requests.put('https://example.uri.com/api/rest/v1/datastorage/' + data_storage['id'],
			 json=data_storage,
			 auth=(client_id, client_secret))

Delete datastorage

API end-point: DELETE /api/rest/v1/datastorage/{dsID}

OAuth requirements: https://oneportal.trivore.com/scope/datastorage.admin scope

Responses:

200 when the data storage was successfully deleted
404 in case the data storage ID was not found or is not deletable

Get all datastorage data

API end-point: GET /api/rest/v1/datastorage/{dsID}/data

OAuth requirements: https://oneportal.trivore.com/scope/datastorage.readonly scope

Get all data that data storage contains.

Responses:

200 when the data in the storage was successfully found
404 in case when data storage was not found

Response body example:

{
  "exampleStringKey": "string",
  "exampleNumberKey": 0,
  "exampleBooleanKey": true
}

Replace datastorage data

API end-point: PUT /api/rest/v1/datastorage/{dsID}/data

OAuth requirements: https://oneportal.trivore.com/scope/datastorage scope

NB! Following operation replaces all data in the data storage with the existing one.

Responses:

204 when the data storage was successfully updated
404 in case when data storage was not found

Examples:

Python requests example code

import requests

exampleData = {
	'exampleStringKey': 'some value',
	'exampleNumberKey': 0,
	'exampleBooleanKey': true,
	'exampleStringKey2': 'second value',
}

# replaces the data in the data storage with the ID 'example id' with the exampleData content
requests.put('https://example.uri.com/api/rest/v1/datastorage/exampleId/data',
			 json=exampleData,
			 auth=(client_id, client_secret))

Get value for a single data key

API end-point: GET /api/rest/v1/datastorage/{dsID}/data/{key}

OAuth requirements: https://oneportal.trivore.com/scope/datastorage.readonly scope

Get a value by the storage ID and a single data key.

Response body example:

{
	"value" : "example value"
}

Responses:

200 when the value was successfully found
404 in case when data storage was not found

Replace single data key value

API end-point: PUT /api/rest/v1/datastorage/{dsID}/data/{key}

OAuth requirements: https://oneportal.trivore.com/scope/datastorage scope

Replace value by the storage ID and a single data key.

Request body example:

{
	"value" : "value to replace with"
}

Responses:

204 when the value was successfully updated
404 in case when data storage was not found

Examples:

Python requests example code

import requests

exampleData = {
	'value': 'value to replace with',
}

# replaces the data in the data storage with the ID 'example id' with the exampleData content
requests.put('https://example.uri.com/api/rest/v1/datastorage/exampleId/data/exampleKey',
			 json=exampleData,
			 auth=(client_id, client_secret))

Clear single data key value

API end-point: DELETE /api/rest/v1/datastorage/{dsID}/data/{key}

OAuth requirements: https://oneportal.trivore.com/scope/datastorage scope

Delete/clear single value by the storage ID and the data key.

Responses:

204 when the value was successfully deleted
400 Bad request (e.g. invalid-id)
404 in case when data storage was not found or not accessible

NOTE: Trivore ID Documentation has moved to https://trivoreid.com

The content on this site IS OUT OF DATE!

This space has been archived!

Please go ahead to the new site!

Basics

Data section

Data read and write operations

Limitations

Remarks on stored data

Data Storage Configurations

Search

OpenAPI Endpoints

List all accessible data storages

Add new data storage

Get datastorage settings

Update datastorage configurations

Delete datastorage

Get all datastorage data

Replace datastorage data

Get value for a single data key

Replace single data key value

Clear single data key value

NOTE: Trivore ID Documentation has moved to https://trivoreid.com

The content on this site IS OUT OF DATE!

This space has been archived!