WebSphere Process Server provides a set of APIs that are implemented using Representational State Transfer (REST) Services.

All data are sent or returned by HTTP methods. These methods are triggered by using the simple client applications shipped with this sample.

Basic sample
In the basic version if the sample, the HelloWorld microflow as known from the "Getting Started > Hello World" sample is started by sending an appropriate HTTP Post request to the WebSphere Process Server. While there are several ways to send a HTTP Post request, two ways are demonstrated in this sample: using a HTML form with some additional JavaScript code, and running a Windows PowerShell script. JavaScript client The first sample client application for the basic sample consists of one single HTML file. This client application allows you to query the process templates installed on the WebSphere Process Server and allows you to start a new instance of the HelloWorld process. Windows PowerShell client The second client application for the basic sample consists of one PowerShell script. By running this script, a new process instance is started synchronously and the response message is written to as console output.

WebSphere Process Server REST Interface

WebSphere Process Server provides a set of APIs that are implemented using Representational State Transfer (REST) Services. The URIs are a set of REST services that access business process, human task, work basket or business category data.

Resource URLs
The URIs of the Business Process Choreographer REST resources 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.

"/v1/{anyResource}?{query}" represents the logical resource

Resource Versioning
Each resource URL 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)

HTTP Methods
The WebSphere Process Server REST interface provides the following HTTP methods:

POST - create a resource GET - read a resource PUT - update a resource DELETE - delete a resource

Content Types
The data sent or returned by the HTTP methods has one of the following content types:

JSON ("Content-Type: application/json") is used for most WebSphere Process Server

resources; for the detailed format of each returned object, see the JSON schema specifications for each operation XML ("Content-Type: application/xml") is used for customer data, that is, input, output, or fault data of processes or tasks, or variable data of a process; the actual format of each expected or returned object is defined in the XML schema provided by the individual process or task Other MIME types can be used for Business Process Choreographer binary custom properties

Simple-Typed XML Data

Some XML data objects represent WSDL message parts or BPEL variables that are defined with an XML schema simple type. In this case, a simple-typed value (which is not a valid XML document by itself) is wrapped within an XML element provided by the Business Process Choreographer REST interface. This wrapper is defined as follows: <xsd:element name="simpleTypeWrapper" type="tSimpleTypeWrapper"/> <xsd:complexType name="tSimpleTypeWrapper"> <xsd:sequence> <xsd:element name="value" type="xsd:anySimpleType" nillable="true"/> </xsd:sequence> </xsd:complexType>

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 below, these objects (in custom properties, client settings, and properties of users/groups) simply appear as generic {"type":"object"}.

Content Localization
For task descriptions, documentations, etc., a client should send the list of preferred languages in the "AcceptLanguage" 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 "ContentLanguage" HTTP header (example: "Content-Language: en").

Content Encoding
HTTP request and response messages may contain compressed data. This is indicated by the "ContentEncoding" 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 may indicate which content encodings are acceptable by using the "Accept-Encoding" HTTP header (example: "Accept-Encoding: gzip"). If the server is unable to respond with any of the listed content encodings then an HTTP status code 406 Not Acceptable is returned. If no "Accept-Encoding" HTTP header 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.

Error Handling
For errors recognized during processing of a WebSphere Process Server REST request, an appropriate HTTP status code is returned to the calling client (e.g., 200 OK or 404 Not Found, see the individual operations for details). Additional error information is provided depending on the error type. For Business Process Choreographer exceptions, the corresponding Business Process Choreographer error number and error message is returned. For severe errors (HTTP status code 500 Internal Server Error), additional information about the problem is returned. You can send this information to IBM service personnel if required.

Security Considerations
Some firewalls do not allow HTTP PUT/DELETE traffic to traverse the firewall because of security considerations. As a workaround, PUT and DELETE requests can be 'tunneled' through a POST using the "X-MethodOverride" or "X-HTTP-Method-Override" HTTP headers. The two headers are synonymous.

BFM Rest Interface:

http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r0mx/index.jsp?topic= %2Fcom.ibm.bspace.help.api.rest.doc%2Frest%2Fwsprocessserver%2Frest_bpm_htm.htm
HTM Rest Interface:

http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r0mx/index.jsp?topic= %2Fcom.ibm.bspace.help.api.rest.doc%2Frest%2Fwsprocessserver%2Frest_bpm_htm.htm