DH Public API Overview

Model Overview

Datahub introduces several interconnected entities

Database
Record
Field
Folder (not to be mistaken with Folder in Wrike)

Database contains Records (rows) and defines their structure via Fields

Records are elements of customer data

Each Record in a Database has the same set of Fields. Each field has its data type along with some type-specific settings

Databases belong to Wrike Spaces and are organized through Folders

Each Wrike Space always have exactly one root Folder

Folders can contain other Folders (which allows to have a complex navigation tree) and Databases

Endpoints/Operations Overview

Navigating folders

All the information within Datahub belongs to spaces and is organized into folders. Each space has exactly one root folder. Each folder (including the root folder) may contain other folders and databases

to get the root folder of a space, use GET /spaces/{spaceId}/root/folder
if a folder ID (or IDs) is already known, use GET /folders?folderIds={ids} or GET /folders/{folderId}
folders form a navigation tree, so you can query subfolders of a known folder GET /folders/{folderId}/folders
It is also possible to query the entity tree using the withDescendants parameter GET /folders?folderIds={ids}&withDescendatnts=true

Retrieving Databases

Databases always reside in folders, so to get a database, we need either its ID or the ID of a containing folder

GET /folders/{folderId}/databases
GET /databases?databaseIds={ids}
GET /databases/{databaseId}

Retrieving Database Structure (Fields)

Databases define the structure (model) of stored records via fields. It is possible to query fields individually (by ID) or in batches

GET /databases/{databaseId}/fields
GET /databases/{databaseId}/fields/{fieldId}

The following system fields are always returned by default for each record and can also be used as filter criteria in queries:

FIid - ID of the record
FIname - title of the record
FIcreatedOn - date when records was created
FIupdatedOn - date when record was updated
FIisRecycled - boolean field, specifying whether the record is recycled/deleted

Retrieving Records

Records can be retrieved individually (by ID) or in batches

GET /databases/{databaseId}/records
GET /databases/{databaseId}/records/{recordId}

Records can be filtered by fields value. Available operators by field type:

Single value type
- All types
  - isNull
  - isNotNull
  - equals
  - notEquals
  - anyOf - except Number and Date types
  - noneOf - except Number and Date types
- String types
  - stringContains
  - stringNotContains
  - stringStartsWith
  - stringEndsWith
- Number and Date types
  - between
  - greaterThan
  - greaterThanOrEqual
  - lessThan
  - lessThanOrEqual
Array value type
- isEmpty
- isNotEmpty
- containsAll
- containsOnly
- intersects
- notIntersects

Creating Entities

To create an entity, issue a POST request to the following endpoints

/folders
/databases
/databases/{databaseId}/fields
/databases/{databaseId}/records
- note that this endpoint allows creating multiple records at once

Editing or Deleting Entities

To edit or delete an entity, issue a PATCH or DELETE request to the following endpoints

/folders/{folderId}
/databases/{databaseId}
/databases/{databaseId}/fields/{fieldId}
/databases/{databaseId}/records/{recordIds}
- note that this endpoint allows deleting multiple records at once

Batch Editing of Records

It is possible to mass-edit multiple records with a single request

PATCH /databases/{databaseId}/records

Pagination Mechanism

Some endpoints may return a large number of entities. To avoid sending too much data at once, we employ a pagination mechanism in:

GET /databases/{databaseId}/records
GET /databases/{databaseId}/fields
GET /folders/{folderId}/databases
GET /databases
GET /folders
GET /folders/{folderId}/folders

Any of these endpoints has an optional pagination parameter which contains

nextPageToken - obtained from the previous page response
limit - how many entities to return in a single page (default=100, max=1000)

The first page is obtained without specifying a page token. Response will contain a token for querying the next page if there is more data which can fit on the page.

📘
Note that page tokens are session-bound so it is impossible to use them after a session expires. Currently the session lasts for up to 3 hours.

Formula Handling

The API does not validate non-existent field IDs, resulting in status code 200. Such fields will be represented with placeholders in the field editor in UI and ignored in calculations.
The API does not validate field operations. For instance, multiplying DATE by DATE cannot yield meaningful calculation. Users who are creating formulas in API should understand the field combinations. Such broken formulas will be shown with a validation error in UI in the field editor.
Only fields from the current database can be used. To use fields from another database, you must create a mirror of that field in the current database.
Formulas and their output types are not validated for mismatched operations. Wrike selects the actual output format based on the operands.
Use the $today variable to represent the today() function.

Idempotency mechanism

It is possible that the API client is unable to tell apart situations where an edit request was not received and processed by the server from situations where a request was processed and the response was lost. For example, this may happen due to network problems. So in the case of duplicated requests from the client, the effect on the system should be the same as the effect of of a single request (this behavior is called idempotent).

The current API guarantees idempotency of PATCH and DELETE requests (as required according to REST practices). Additionally, POST requests are designed in a way to support idempotency. That is why the request body for all POST requests has to contain a requestId field. The client has to generate a unique requestId for each request. In the case of a retry, the client should use the same requestId as was sent with the request that is being retried. You can use any non-empty value for the requestId field, good practice is to use a freshly generated UUID.

📘
Note that for POST endpoints idempotent retry is supported within a short period of time after the initial request (3 hours). This time period is an implementation detail and is subject to change without notice.