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.

1. Create a REST Services project (File > New > REST Services Project).
2. On the General tab of the Properties view for the REST Service Descriptor, add the Context Path for the REST service.

   The context path is used in the URL for the service at runtime. Context Path is a common path prefix that is used for all resource URLs in this service. For example, /rest/test/2. The context path is applied to the beginning of all resource paths.

   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.
3. Configure resources (including a Path Template and Path Parameters, which are 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).

   The URL for the REST invocation method is built up from the following: <baseurl> + context path + template path.

   where <baseurl> is http://localhost:8080, context path is /rest/test/2, template path is /issue/{issueId}.

   For example:

   http://localhost:8080/rest/test/2/issue/{issueId}

   The <baseurl> is provided by the HTTP Client shared resource associated with the REST service task participant during project deployment.

4. 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.
5. 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 a 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.

   If you declare an error, you can also declare a JSON type for the information coming back and map it to process data using a catch error event attached to the REST service task.

   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.