RESTful Storage
Client Storage provides a mechanism to keep and manipulate custom data with REST calls.
Resources
Here's the list of resources in Client Storage:
Client Storage Group
Represents a group of storages. It contains only one field: Name
. You need to specify a unique Name (for example Boards).
Client Storage
Storage itself. It contains common and user-specific data, and has the following fields:
- Key - a unique storage identifier. Can be specified by a user. For example, JaneKanban
- Scope - can be 'Public' or 'Private'. The public storages are available to everyone, the private ones - only to their owners.
- OwnerId - owner ID. Can't be specified explicitly, is set automatically as the storage is created.
- PublicData - key-value collection with common storage data.
- UserData - key-value collection with user-specific data.
API
Get groups
GET /storage/v1/
Returns storage names:
{
"items":[
"Boards",
"UI"
]
}
Permissions: anyone can get groups.
Get storages
GET storage/v1/{StorageGroupName}
Returns storages from the group.
{
"items":[
{
"key":"Kanban-123",
"ownerId":184,
"scope":"Private",
"publicData":{
"color":"red"
},
"userData":{
"filter":"empty"
}
},
{...}
]
}
Permissions: owned or public storages will be returned. User data will be returned for the current user
Delete storage group
DELETE /storage/v1/{StorageGroupName}
Deletes a storage group and returns an empty result.
Permissions: only Administrator can delete a storage group.
Get storage
GET /storage/v1/{StorageGroupName}/{StorageKey}
Returns storage.
{
"key":"Kanban-123",
"ownerId":187,
"scope":"Public",
"publicData":{
"color":"red",
"tau":"epsilon"
},
"userData":{
"color":"white",
"position":"absolute"
}
}
Permissions: user can get only owned or public storage. User data will be returned for current user.
Post/Put to storage
POST /storage/v1/{StorageGroupName}/{Key}
{
"scope":"Public",
"publicData":{
"color":"white",
"size":"xxl"
},
"userData":{
"color":"purple",
"filter":"empty"
}
}
POST /storage/v1/{StorageGroupName}/{Key}
{
"scope":"Public",
"publicData":{
"color":"white",
"size":"xxl"
},
"userData":{
"color":"purple",
"filter":"empty"
}
}
Use this URL to create/update storage. Key is the identifier. So, if you post storage with a non-existing key, Targetprocess will create a new Storage.
When you post PublicData or/and UserData, the value of dictionary will not be overridden.
If you post value with a non-existing key, this key-value pair will be added to the dictionary.
If you post value with an existing key, the value will be overridden with posted value.
If you post null for an existing key, this key-value pair will be removed from the dictionary.
Permissions: Scope and PublicData can be changed only by Owner or Administrator. Any user can change his/her UserData. Key cannot be changed.
If you post to a non-existing group and/or storage, it would be created automatically. So, there's no need to check if a group or storage has been created.
Post to storage
POST /v1/{StorageGroupName}
Same as the Post/Put above. Key will be auto-generated, if not specified explicitly.
Delete storage
DELETE /storage/v1/{StorageGroupName}/{StorageKey}
Deletes storage and returns an empty result.
Permissions: only Admin or Owner can delete storage.
Querying
API provides querying. Use the select and where clauses when asking for a collection of resources.
Here are some examples:
Find all public storages in group Boards:
GET /storage/v1/Boards?where=(scope == "Public")
Select keys, names from PublicData and filters from UserData for all storages in Boards:
GET /storage/v1/Boards?select={key, publicData.name, userData.filter}
Get paged data:
GET /storage/v1/Boards?take=20&skip=20
Find all private storages where PublicData.name is 'Kanban':
GET /storage/v1/Boards?where=(scope == "Private" and publicData.name == "Kanban")&select={key, scope, publicData.description}
A few more sample requests:
GET /storage/v1/Boards/?where=(scope == "Private")&select=(new(key, scope, data["size"] as size, userData["filter"] as filter))
GET /storage/v1/Boards/?where=(scope == "Private")&select={key, scope, data.size, userData.filter}
Use case - pull all the views:
GET /storage/v1/boards?prettify&select={key,ownerids,scope,publicData.name,publicData.description,publicData.x,publicData.y,publicData.cells,userData.user}
Updated almost 2 years ago