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:

Table 1. HTTP methods
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&params={"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&params={"orderNumber":"5","customerName":{"firstName":"John","lastName":"Doe"}}