About Me
Facebook
Facebook
Linked In
Linked In
Twitter
Twitter
YouTube
YouTube
Google +
Google +

Sunday, April 17, 2016

Using the REST APIs in IBM Business Process Manager V8.5

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>

continue reading

Designed By AMEER BASHA G