Process Engine REST Service

Authentication

The REST Service resource requests require the calling client to be authenticated by using HTTP Basic authentication. The client's authorization for accessing REST operations on a specified resource is determined by the permissions that are assigned to the resource.

Resource Data Format

The REST Service resources use the JSON MIME type (content-type="application/json") and query string format for request and response data. Long query strings can be an exception to this rule (see the section URL Length Limitation). All data needs to be in UTF-8 format (both for query strings and data in the request body).

Date Fields

For date fields, the value is a string in the ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time. For example, 2008-03-13T19:49:00Z.

URL Length Limitation

URLs used for GET operations with complex queries might result in long query strings. Browsers can handle relatively long request strings, but size might still be of concern. In such cases, the client detects this condition and changes the GET request to a POST request. The query parameters (without "?") are in the body of the POST request with the content type set to application/x-www-form-urlencoded.

For example, the POST statement:

POST /queues/{queue}/workbaskets/{workbasket}/queueelements
Content-Type=application/x-www-form-urlencoded

filters=[State=CA, City=Costa Mesa] &pageSize=50 &queryFlags=1 &orderBy=State &lastRecord = xxxxxx

is equivalent to the following GET statement:

GET /queues/{queue}/workbaskets/{workbasket}/queueelements?filters=[State=CA, City=Costa Mesa]&pageSize=50&queryFlags=1&orderBy=State& lastRecord =xxxxxx

Resource Navigation

When you navigate between REST resources, it is best practice to follow the URIs found in the response instead of manually constructing the URIs. This practice allows for future optimization, where the server can provide the optimal URI for navigating to a resource.

The base URI for all REST resources is:

    http://host:port/{context}/{servlet}/p8/bpm/v1/

This base is not included in the response URIs. Each client is to be configured with the base URI. This base URI value can then be prepended to the URI found in the response.

Example

A client fetches the list of roles for the current user by navigating to the known URI:

    http://host:port/{context}/{servlet}/p8/bpm/v1/appspaces/{appspace}/myroles

The client receives the following JSON response for the myroles resource:

{
  "Agent":{"name":"Agent","URI":"appspaces/Autoclaim/roles/Agent"},
  "Manager":{"name":"Manager","URI":"appspaces/Autoclaim/roles/Manager"
}

The client then navigates to the Agent role by prepending the base URI to the value of the URI property in the response:

    "http://host:port/{context}/{servlet}/p8/bpm/v1/" + "appspaces/Autoclaim/roles/Agent"

Error handling

Errors that are recognized during the processing of a REST Service request, return an appropriate HTTP status code (such as 200 OK or 404 Not Found).

Specifying a Locale

Use the Accept-Language HTTP Request Header field to specify the languages that are preferred as a response to the request. The Process Engine REST Service calls in to the Process Java™ API. It uses the standard XLIFF (XML Localization Interchange File Format) files for translation.

For more information, see Create an XLIFF file and Lookup precedence for locale resources.