IBM Business Process Manager, Version 8.5.0

REST interface for IBM BPM repository resources

IBM Business Process Manager provides a set of APIs that are implemented using Representational State Transfer (REST) services. A set of REST resources is provided for accessing business process, human task, work basket or business category data.

Resource URIs

The IBM Business Process Manager REST resource URIs have the following format:

http://{host}:{port}/bpm/repo/{anyResource}?{query-string}

where:

HTTP Methods

The IBM Business Process Manager REST interface provides the following HTTP methods:

Security Considerations

Some firewalls do not allow the use of HTTP PUT and DELETE methods to flow through the firewall because of security considerations. To accommodate this, a PUT or DELETE request can be 'tunneled' through a POST request using the "X-Method-Override" or "X-HTTP-Method-Override" HTTP header. In general, the value of the X-Method-Override and X-HTTP-Method-Override HTTP headers act as an override to the HTTP method used in the request.

As an alternative to setting the X-Method-Override or X-HTTP-Method-Override HTTP headers, you can use the "x-method-override" or "x-http-method-override" URI query parameter (example: "POST /rest/bpm/htm/v1/task?...&x-method-override=PUT").

URI Length Concerns

In some cases, the length of a GET request URI might exceed the URI length supported e.g. by a browser or it might be otherwise impractical to specify all the request parameters as query parameters. As a workaround, a GET request can be 'tunneled' through an equivalent POST.

In this case, the client replaces the GET method by a POST method, puts the URI query string (the string to the right of the '?' character) into the POST request message body, and sets the Content-Type HTTP header to "application/x-www-form-urlencoded".

Media Types

The data included in requests or responses will be of one of the following media types:

application/json
JSON (JavaScript Object Notation) - This is the default response content type. For the detailed format of each returned object, see the JSON schema specifications for each operation.
application/xml
XML (eXtensible Markup Language) - The format of XML-based data is specfied by the XML schemas supplied with the product in the <install-root>/properties/schemas/bpmrest/v1 directory. Excerpts of these schemas are also provided in the documentation for each operation.

Requesting Response Media Types

A client can specify the requested media type for the response by using the "Accept" HTTP header (example: "Accept: application/json").

Alternatively, the client can use the "accept" URI query parameter (example: "GET /rest/bpm/htm/v1/task/...?accept=application/json"). If both the HTTP header and the URI query parameter are specified, then the query parameter takes precendence.

If the server is unable to respond with the requested media type then an HTTP status code 406 Not Acceptable is returned.

Content localization

Requesting localized response content

For task descriptions, documentations, etc., a client should send the list of preferred languages in the "Accept-Language" HTTP header (example: "Accept-Language: da, en-gb;q=0.8, en;q=0.7" - "I prefer Danish, but will accept British English and other types of English"). The server responds with a "Content-Language" HTTP header (example: "Content-Language: en").

Instead of setting the HTTP header, the client can use the "accept-language" URI parameter (example: "GET /rest/bpm/htm/v1/task/...?accept-language=en").

Content encoding

HTTP request and response messages might contain compressed data. This is indicated by the "Content-Encoding" HTTP header (example: "Content-Encoding: gzip").

If the request message has a content encoding that is not recognized by the server then an HTTP status code 415 Unsupported Media Type is returned.

Requesting encoded response content

A client can specify which content encodings are acceptable by using the "Accept-Encoding" HTTP header (example: "Accept-Encoding: gzip") or the accept-encoding URI query parameter (example: "GET /rest/bpm/wle/v1/task/...?accept-encoding=gzip").

If no "Accept-Encoding" HTTP header (or accept-encoding URI query parameter) is specified in the request message, then by default the content encoding of the response message is "identity" (no encoding), indicated by the absence of the "Content-Encoding" HTTP header.

If the server is unable to respond with any of the listed content encodings then an HTTP status code 406 Not Acceptable is returned.

Supported HTTP Headers and General Parameters

The following list provides a summary of supported HTTP headers and general URI query parameters applicable to any resource URI:

If both an HTTP header and its corresponding URI query parameter are specified, then the URI query parameter value takes precedence over the HTTP header value.

Error Handling

For errors recognized during processing of a REST request, an appropriate HTTP status code is returned to the calling client (see the individual operations for details). The following HTTP status codes are returned by IBM Business Process Manager REST methods:

Exception details

By default, an error response will omit the server-side exception details because of security considerations. To enable the inclusion of server-side exception details, you must set the following property in the server's 100Custom.xml file:

<server-stacktrace-enabled>true</server-stacktrace-enabled>

References

IBM Business Process Manager information center resources:

Additional standard specifications:

Subtopics

The following subtopics describe the resource sets defined for this product: