Endpoints for Entity Objects
Use these endpoints to get, create, update, or delete entity objects in your ProcessMaker IDP instance. Optionally, filter, sort, and/or paginate results when you receive results.
Base URL for Entity Object Endpoints
You can access the server via https://{idp-server}/datastore/api/rest. Each entity type has its own endpoint and is identified by its type: /{type}.
Gets a collection of entity objects by their type.
GET https://{idp-server}/datastore/api/rest/{type}
See 200 status code response for cURL example.
Path Parameters
type*
String
Entity type to get.
Example of getting a collection of file entities:
cURL request:
Gets one type's entity object by its unique ID.
GET https://{idp-server}/datastore/api/rest/{type}/{id}
See 200 status code response for cURL example and response example.
Path Parameters
type*
String
Entity type related to the entity to get.
id*
String
Unique ID of the entity to get in that type.
Example of getting a file entity with ID d72c9a40-8ef1-4c16-94c8-038cd9b80089:
cURL request:
Example response:
The request was okay and the response body contains the representation requested.
Gets the content (binary) of a type's entity object by its unique ID.
GET https://{idp-server}/datastore/api/rest/{attribute}/{type}/{id}
Unlike other GET method endpoints, this endpoint uses a type entity called file. The attribute that contains the binary, which is the file to download, is called content.
See 200 status code response for cURL example.
Path Parameters
attribute*
String
Attribute that contains the binary.
type*
String
Entity type related to the entity to get.
id
String
Unique ID of the entity to get in that type.
Example of getting a file entity with ID 17478078-52cf-4472-ab98-1b27a10b71c9:
cURL request:
Gets resources related to an entity object.
GET https://{idp-server}/datastore/api/rest/{type}/{id}/{relation}
See 200 status code response for cURL example.
Path Parameters
type*
String
Entity type related to the entity to get.
id*
String
Unique ID for the entity to get in that type.
relation*
String
Relation name for the entity to get.
Example of getting a folder with name 5f97858b-26e3-4180-80c4-25b176cbc35f:
cURL request:
Filter by name of entity object result.
GET https://{idp-server}/datastore/api/rest/{type}?filter%5Bname%5D={name}
Note: Due to an issue in Spring Framework, URL parameters in GET requests do not properly url-encode. When filtering for an entity containing a + character in its name, there are two ways to process this (see examples). For example, for the file Welcome + to + IDP.docx the + symbol gets encoded.
See 200 status code response for URL examples. See examples 3 and 4 how to address the + character issue.
Path Parameters
type*
String
Entity type related to the entity to get.
name
String
Name of the entity object from which to filter results. Use exact characters as the entity object is named, including spaces. Note exception above regarding the + character.
Example 1: Example for an entity filtered on name Welcome to IDP.docx:
Example 2: Example that uses multiple filters:
Example 3: Option 1 to encode the + character in a GET request:
Example 4: Option 2 as alternative to encoding the + character by using a POST request:
Sort results by providing the attribute(s) from which to sort, followed by sorting direction.
GET https://{idp-server}/datastore/api/rest/file?sort=
By default, results are sorted in ascending order. To sort in the opposite direction, add a minus character (-) preceding the attribute name.
See 200 status code response for cURL example.
Example of a request to read files sorted in descending order by creation date:
Paginate results.
GET https://{idp-server}/datastore/api/rest/file?count=
The ProcessMaker IDP REST API uses cursor-based pagination (also known as keyset pagination).
When no parameters for pagination are provided, default values for pagination apply. The returned response contains links that refer to the next and previous pages. Default count per page is 20.
See 200 status code response for cURL example.
Path Parameters
after
Integer
Returns the first item immediately after the cursor in the results list. Typically use to get the next page.
before
Integer
Returns the last item in the paginated data to be closest to, but still before, the cursor in the non-paginated results list. Typically use to get the prior page.
count
Integer
Number of entities per page.
Example of a request with pagination parameters:
cURL request:
Example response:
Creates an entity object by specifying its entity type.
POST https://{idp-server}/datastore/api/rest/{type}
See 200 status code response for examples and a response example.
See below this endpoint description for example how to create a file entity with a file.
Path Parameters
type*
String
Entity type to create.
Request Body
data*
JSON String
Attributes specified as key/value pairs. When creating files or subfolders in a dossier, parentId JSON object is required.
file
Binary Data
File to upload with your entity.
Example to create a dossier:
type is an attribute of FOLDER. Specify the name of the new dossier in the name JSON object.
Example to create a folder:
type is an attribute of FOLDER. Specify the name of the new folder in the name JSON object. parentId is required only when creating a folder to specify in which folder or dossier to create the new folder.
Example to create a file:
Specify the name of the new file in the name JSON object.
Example response after successfully creating an entity object:
The request was okay and the response body contains the representation requested. The response contains all attributes of the created entity. This includes auto-generated attributes.
Updates one type's entity object by its unique ID.
PUT https://{idp-server}/datastore/api/rest/{type}/{id}
See 200 status code response for cURL example and response example. See below this endpoint description for example how to update a file entity with another file, thereby replacing it.
Path Parameters
type*
String
Entity type related to the entity to update.
id*
String
Unique ID for the entity to update in that type.
Request Body
data
JSON String
Attributes specified as key-value pairs.
file
Multipartfile
The file to update.
Example of updating a file entity with ID d72c9a40-8ef1-4c16-94c8-038cd9b80089, where both the attributes and the binary will be updated:
cURL request:
Example response:
The request was okay and the response body contains the representation requested. The response contains all attributes of the updated entity.
Deletes one type's entity object by its unique ID.
DELETE https://{idp-server}/datastore/api/rest/{type}/{id}
See 200 status code response for cURL example. See below this endpoint description for example how to delete a file entity.
Path Parameters
type*
String
Entity type related to the entity to delete.
id*
String
Unique ID of the entity to delete in that type.
Example of deleting a file entity with ID d72c9a40-8ef1-4c16-94c8-038cd9b80089:
cURL request:
Errors
ProcessMaker IDP uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
Codes in the
2xxrange indicate success.Codes in the
4xxrange indicate an error that failed given the information provided (such as a required parameter was omitted or the provided ID does not exist).Codes in the
5xxrange indicate an error with ProcessMaker IDP’s servers.
Most 4xx errors will return a message that briefly explains the reported error.
Example of an error message: Status 400 Bad Request:
Last updated