Defining the Interface to an External REST Service

To call a REST Service you need to create a REST Service Descriptor (RSD) file (located in a separate REST Service project). The REST method from the RSD file can then be referenced from REST Service invocation activities.

The purpose of the REST Service Descriptor (RSD) is to define the end-point URL relative resource path (optionally including query and header parameters), the available methods for the resource and the request-response data details for those methods.

Note: You should not use URL encoding (for instance %20 for spaces) in the Context Path of the Resource path definition in the REST Service Descriptor. Also, you should not encode values in Path Parameters (that is, the value of data fields mapped to those parameters). This is because the path and parameter values are automatically encoded at runtime. If there is a use case where the path may require URL delimiter characters (such as /, @ , ? etc) that need to be encoded then simply use a path parameter in the required location and then provide the required unencoded values in the data mapped to the parameter.

Procedure

  1. Create a REST Services project (New > Other > REST Services Project).
    Note: REST Service Descriptor (RSD) projects do not need to be deployed.
  2. A REST Service Descriptor is created automatically.
    To create an additional REST Service Descriptor, select New > New REST Service Descriptor.
    The service descriptor can be used by multiple REST service activities.
  3. Add the Context Path for the REST service, which will be used in the URL for the service at runtime. Context Path is a common path prefix that will be used for all resources' URLs in this service. For example, /rest/api/2. The context path is applied to the beginning of all resource paths.

  4. Configure resources (including a Path Template and Path Parameters which will be used in the URL for the method). Path Template may contain path parameter references. Parameter reference is constructed using the name of the parameter enclosed between { and } characters.

    Path parameters are variable parts of the path URL that are replaced with process data at runtime (by mapping process data to the parameters in the REST service invocation task).

  5. The URL for the REST invocation method is built up from the following: <baseurl> + context path + template path).
    For example: http://localhost:8080/rest/api/2/issue/{issueId} (where <baseurl> is http://localhost:8080, context path is /rest/api/2, template path is /issue/{issueId}.
    The <baseurl> is provided by the HTTP Client shared resource associated with the REST service task participant during project deployment.
  6. Add HTTP method/s for each resource, and select the HTTP Method type from GET, PUT, POST or DELETE.
    The GET method is already added by default for each resource.

    The Request Overview provides an idea of what the final URL for the REST invocation method will be.
  7. Create request and response information using the method in the Request and Response tabs. On each method, you can define Query Parameters/Header Parameters and Payload (which must be a JSON schema type). See Creating JSON Schemas.
    The PUT and POST methods have the Request Payload specification.
    • Query Parameters: for example, http://localhost:8080/?param1={param1} where{param1} is a query parameter added using the Request tab.

    • Payload Type: Select from existing JSON objects.
      Note: If you cannot create the exact JSON object using the REST service task mapper (or the payload is not in JSON format), you can configure the REST method definition request payload type to be Unprocessed Text. In the REST Service task process create a text field whose value is the required JSON string and map that to the request payload.
    • Content Type: needs to be set to that defined by the service.
    • Header Parameters: some services require header parameters to be passed, also a service can return header parameters. These can be mapped from and to process data in an invocation task.

    Use the Faults tab on the method in the REST Service project to define faults for specific error status codes.

    If you declare an error you can also declare a JSON type for the information coming back and map it to local data.

    Note: HTTP response status codes 300 and above are automatically treated as errors at runtime. You can catch any such error with a 'Catch All' task boundary error event or you can define faults for specific status codes that can be caught individually.