HTTP methods supported by the IBM BPM REST APIs
The HTTP methods provide the operations, such as create, read, update, and delete that you can perform on IBM® BPM artifacts.
The following HTTP methods are supported:
HTTP method | Description |
---|---|
POST | Creates a new resource. |
GET | Retrieves a resource. |
PUT | Updates an existing resource. |
DELETE | Deletes a resource. |
The GET method is a safe method because the state of the resource remains unchanged by this operation.
Important: The IBM BPM REST
APIs report time zones in Coordinated Universal Time (UTC) format.
If
you want your application to display the date or time (or both) in
a different time zone, you can get an instance of java.text.DateFormat,
set the TimeZone you want on it, and then call format,
passing the Date object that you want to display.
The following code snippet uses the default time zone in which the
application is running:
// Assuming that "dateFromREST" is a java.util.Date object
DateFormat df = DateFormat.getDateTimeInstance();
TimeZone tz = TimeZone.getDefault();
df.setTimeZone(tz);
String formattedDate = df.format(dateFromREST);
// formattedDate has the date you want to show to the user.
Security considerations
When using HTTP methods, consider the following security aspects:
- Some firewalls do not allow HTTP PUT or DELETE traffic
through the firewall because of security considerations. To accommodate
this restriction, you can send these requests in one of the following
ways:
- Use the X-Method-Override or X-HTTP-Method-Override HTTP header fields to tunnel a PUT or DELETE request through a POST request.
- If the request is for a BPD-related resource, you can use the x-method-override or the x-http-method-override URI parameters. For
example:
POST /rest/bpm/htm/v1/task?...&x-method-override=PUT
- You can use some of the HTTP methods for the BPD-related resources
to evaluate JavaScript expressions. Because of security considerations,
JavaScript support is not enabled by default. To enable JavaScript
support, set the associated property in the 100Custom.xml file
for the process server:
<properties> <common> <enable-javascript-execution>true</enable-javascript-execution> </common> </properties>
URI length considerations for REST API requests
In some situations, the length of a REST API request URI might exceed the supported URI length, for example, because of browser restrictions, or the number and length of query parameters in the request URI.As
a workaround, you can tunnel your request through a POST request
that uses the application/x-www-form-urlencoded content
type. To exploit the workaround, construct the REST API request in
the following way:
- Use the POST method in the HTTP request.
- Set the X-HTTP-Method-Override HTTP header to the intended method from your original request. For example, if you intended your original request to be a PUT request, then set the value of this header to PUT.
- Set the value of the Content-Type HTTP header to application/x-www-form-urlencoded.
- Add all of the request parameters from your original request URI query string to the HTTP request body.
For example, you need to call the following REST API to
set some output variables to finish a task instance but the request
URI is too long:
PUT http://host1.company.com:9080/rest/bpm/wle/v1/task/3?action=finish¶ms={"orderNumber":"5","customerName":{"firstName":"John","lastName":"Doe"}}
Headers:
Accept application/json
The following HTTP request shows
how to call the same API using the application/x-www-form-urlencoded content
type:POST http://host1.company.com:9080/rest/bpm/wle/v1/task/3
Headers
Accept application/json
Content-Type: application/x-www-form-urlencoded
X-Method-Override: PUT
Request Body:
action=finish¶ms={"orderNumber":"5","customerName":{"firstName":"John","lastName":"Doe"}}