IBM Business Process Manager, Version 8.5.5
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.
The IBM Business Process Manager REST resource URIs have the following format:
http://{host}:{port}/rest/{component}/v1/{anyResource}?{query}
where:
Each resource URI has a version identification (/v1) for handling changes to the REST API set that would break compatibility with existing REST clients. The following changes are considered compatible and must be expected by clients:
The IBM Business Process Manager REST interface provides the following HTTP methods:
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").
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".
The data included in requests or responses will be of one of the following 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.
Some requests support the parts URI query parameter, which is an optional parameter that allows a client to specify a list of one or more parts to be returned in the response data for a particular request.
Examples:
parts=header|data
parts=all
parts=none
In general, the value of the parts parameter is a "|"-delimited list of part names. Each request will support its own particular set of part names that are associated with that request. For those details, see the reference information for each request. In addition to specific parts names, you can also specify "all" or "none". If the parts parameter is not specified, then the default of "all" will be used.
Some JSON data objects contain a nested object with a list of name/value pairs such as { "a" : "Athens", "b" : "Belgrade", "c" : "Cairo" }. In the JSON schema descriptions throughout the documentation, these objects (in custom properties, client settings, and properties of users/groups) simply appear as generic {"type":"object"}.
To request that response data is to be returned in the JSONP format, you must specify a response media type of application/x-javascript with either the Accept HTTP header or the accept URI query parameter, and you must also specify the javascript function name with the callback URI query parameter. In this case, the response consists of the JSON content wrapped in a JavaScript callback function invocation. Example: "GET /rest/bpm/wle/v1/task/...?accept=application/x-javascript&callback=mycallback".
By default, the support for JSONP is disabled because of security considerations. To enable JSONP support, you must set the following property in the server's 100Custom.xml file:
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").
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.
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.
The following list provides a summary of supported HTTP headers and general URI query parameters applicable to any resource URI:
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:
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:
IBM Business Process Manager information center resources:
Additional standard specifications:
The following subtopics describe the resource sets defined for this product: