Page Comparison

Permalink: https://doc.oneportal.fi/x/dYAW

The Cloud Database is a 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 owndata storage entry has:

• 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 or a groups of 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:

...

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.

  Anchor
  config config

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.

...

{
  "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.

...

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

...

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

...

• 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

...

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

...

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}

...

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}

...

• 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

...

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

Replace datastorage data

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

...

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}

...

• 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}

...

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}

...