Constructing REST Requests

REST API requests must be submitted in a specific format.

The format of a BPM REST API request is:

<METHOD> <baseurl>/<REST_call>/<path_parameters>?<query_parameter>&<additional_query_parameter>

where:

  • <METHOD> is the HTTP method to be used on the resource (GET, POST, PUT or DELETE).
  • <baseurl> is the ActiveMatrix BPM REST API Endpoint ( baseurl ).
  • <REST_call> consists of one or more terms that describe the request. If more than one term is required, they are separated by a forward slash. For example, to request the organization model, the following syntax is used: 
    GET <baseurl>/orgmodel/model/<version>

    The "/orgmodel/model" part is the <REST_call>.

  • <path_parameters> provide information needed to make the request. In the example shown above, <version> is a path parameter.

    Some requests do not require path parameters.

    Some requests require multiple path parameters, in which case, they are separated by forward slashes. For example, in the following request to cancel an ad hoc activity, a process ID and an activity ID must be passed: 

    DELETE <baseurl>/process/adhoc/cancel/<processid>/<activityID>
  • <query_parameters> provide additional information for the request. These parameters are optional. If provided, the first query parameter must be preceded by a ? character. Multiple query parameters must be separated by ampersand (&) characters.

    Query parameters are passed in the form of parameter_name=value. For example, in the following request to delete a calendar, "namespace" is a query parameter, and "LONDON" is its value: 

    DELETE <baseurl>/calendar/LONDON00/0?namespace=LONDON

Example

The following is an example call to the getLdapEntry operation, which illustrates a request that includes all of the elements described above: 

GET http://localhost:8080/bpm/rest/directory/entry/easyAs/ou=Jon%20Parkin,ou=Paris,ou=AllEmployees,o=easyAsInsurance?attrname=employeetype&attrname=userpassword

where:

  • GET is the HTTP method.
  • http://localhost:8080/bpm/rest/ is the baseurl.
  • directory/entry is the REST call.
  • easyAs/ - The first path parameter.
  • ou=Jon%20Parkin,ou=Paris,ou=AllEmployees,o=easyAsInsurance is the second path parameter.
  • ?attrname=employeetype is the first query parameter.
  • &attrname=userpassword is the second query parameter.

All entries in the request URL must be URL encoded (like "Jon%20Parkin" in the second path parameter in the example above). For more information, see URL Encoding Path and Query Parameters.

Some REST operations also require that a data payload be passed in the request body. For more information, see Data Payloads and Supported Media Types.