Introduction
This article describes the
REST resources available for application developers to use in IBM® Business
Process Manager to access business process, human task and business category
data. This article introduces the various components of Business Process
Manager that are exposed in the REST APIs, as well as supported content types,
use of method overrides, response data formats, and how to use the REST API
Tester tool.
Overview
IBM Business Process Manager
V8.5 provides a set of APIs that are implemented using Representational State
Transfer (REST) services. A set of business process definition (BPD) related
REST resources are provided for accessing business process, human task and
business category data. These REST APIs enable developers to build a user
interface or customize an existing portal application. The APIs are simple
enough to be called from mobile devices or from Rich Internet Applications
(RIAs).
This article introduces the
IBM Business Process Manager REST APIs you can use to access business process,
human task and business category data, and describes the various components of
Business Process Manager that are exposed in the REST APIs. You'll learn about
the following:
Ø
The REST URL
format
Ø
The available REST
APIs
Ø
Supported content
types and use of method overrides
Ø
Response data
formats
Ø
The REST API
Tester
BPM components and data models
The Business Process Manager
REST APIs work with various BPM components. Below Figure illustrates all
Business Process Manager components for which a REST APIs are implemented, and
their associated data models.
Several REST methods are
available for application developers to use on each resource; these methods are
listed in the next section. Following is the list of Business Process Manager
components in which various product functions are exposed in REST APIs:
v Business process definitions
v Process instances
v Tasks
v External activities and services
v Users and groups
v Saved searches and custom searches
The IBM Business Process
Manager REST resource URIs have the following format:
http://{host}:{port}/rest/{component}/v1/{anyResource}?{query}
where:
·
"http://{host}:{port}" contains
the host address and port
·
"/rest/{component}" is
the configurable context root, where component (providing a resource set) is
e.g. bpm/htm or bpm/wle.
·
"/v1/{anyResource}?{query}",
together with the host address/port and context root, represents the IBM
Business Process Manager resource
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:
·
Adding new REST
resource relationship to the resource model, without affecting existing
navigation
·
Adding additive
information to REST representations that won't affect existing clients
·
Adding a new MIME
type / representation support
·
Adding new
properties to existing JSON objects returned to a client (ignored by backlevel
clients)
·
Adding new
properties to existing JSON objects received from a client (defined as
optional)
The IBM Business Process
Manager REST interface provides the following HTTP methods:
·
POST - create a
new resource
·
GET - retrieve a resource
·
PUT - update an
existing resource
·
DELETE - delete a
resource
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:
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.
application/x-javascript
JSONP (JSON with Padding) - This format can be used as an alternative to JSON.
In this case, each returned JSON response is wrapped in a JavaScript callback
function invocation. To use this feature, you must also specify
the callback URI query parameter.
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.
Requesting Parts in the Response Data
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.
JSON Lists of Name/Value Pairs
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"}.
JSONP Response (WebSphere Lombardi Edition only)
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:
<jsonp-enabled>true</jsonp-enabled>
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").
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.
The following list provides a
summary of supported HTTP headers and general URI query parameters applicable
to any resource URI:
·
HTTP headers:
o "Accept" - used to specify the
acceptable media type(s) for the response
o "Accept-Encoding" - used to specify the
acceptable content encodings for the response
o "Accept-Language" - used to specify the
set of natural languages that are preferred in the response
o "Content-Encoding" - specifies which
content codings have been applied to the request or response
o "Content-Language" - specifies the
natural language(s) used in the request or response
o "Content-Type" - specifies the media
type of the request or response message body
o "X-Method-Override" - indicates the
HTTP operation that is tunneled through this request; in other words, this
specifies a method name which overrides the method specified in the HTTP
request header.
o "X-HTTP-Method-Override" - equivalent
to "X-Method-Override"
·
URI parameters:
o "accept" - equivalent to
the "Accept" HTTP header
o "accept-encoding" - equivalent to
the "Accept-Encoding" HTTP header
o "accept-language" - equivalent to
the "Accept-Language" HTTP header
o "callback" - name of the JavaScript
callback function used in JSONP responses; this URI query parameter is required
if the caller requests the application/x-javascript media type in the response
by setting the Accept HTTP header or the accept URI query
parameter.
o "x-method-override" - equivalent
to "X-Method-Override" HTTP header
o "x-http-method-override" - equivalent
to "X-HTTP-Method-Override" HTTP header
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.
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:
·
Successful completion of the request:
o "200 OK" - successful completion
o "201 Created" - successful completion,
new resource created
o "204 No Content" - successful
completion, no content available
·
Expected error situations - additional error
information is provided depending on the error type:
o "400 Bad Request" - parameters are not
valid or they are missing
o "401 Unauthorized" - caller is not
authorized for this request
o "403 Forbidden" - caller is not allowed
to complete this request
o "404 Not Found" - resource does not
exist
o "406 Not Acceptable" - unsupported
media type or content encoding requested
o "409 Conflict" - conflict exists with
the current state of the resource
o "415 Unsupported Media Type" -
unsupported media type or content encoding of the request
·
Unexpected error:
o "500 Internal Server Error" - severe
problem - programmer's details provided
o "501 Not Implemented" - used for
certain federated requests
o "503 Service Unavailable" - federated
requests could not be delivered to individual federation targets
o "504 Gateway Timeout" - federated
response has partial content because of missing individual responses
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>
