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}