WebSphere Process Server, Version 6.2.0.1 Operating Systems: AIX, HP-UX, Linux, Solaris, Windows, i5/OS, z/OS


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 and task 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:

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:

HTTP Methods

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

Content Types

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

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 "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").

Content Encoding

HTTP request and response messages may 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 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-Method-Override" or "X-HTTP-Method-Override" HTTP headers. The two headers are synonymous.

References

The following specifications provide additional helpful information:

Subtopics

The following subtopics describe the REST resource sets defined for WebSphere Process Server: