Using Custom Endpoints with RESTCaller

Using custom endpoints in orchestrations enables you to externalize the location of a REST resource from the orchestration design. If you have defined a custom endpoint to use with your REST service calls, the custom endpoint implementation enables you to access endpoint data and dynamically extend the URL. Following are some ways you can use custom endpoints with RESTCaller:

Use Case #1: Setting Authentication Based on the Custom Endpoint

You can use the authentication set in a custom endpoint as the authentication for the REST service call that will be made by your RESTCaller step. To configure this, do the following:

Use the Custom Endpoint Url field as the resource URL or a base to calculate the resource URL and map the result to the RESTCaller restUrl parameter.
Set the RESTCaller authorizationType to ENDPOINT.
Map the custom endpoint EndpointID field to httpAuthorization > endpoint > endpointID.

Note: For some authorization types you can map the custom endpoint information to the appropriate RESTCaller fields rather than use the ENDPOINT authorization type.

Use Case #2: Using Different Servers for Different Environments

The typical use case is where you may have a resource server for the QA environment and a separate resource server for the Production environment. For example:

QA:

http://qaserver:port/resources/resource

Production:

http://productionserver:port/resources/resource

While the resource path is constructed the same way in both cases, the server address is different. By creating a custom endpoint, you can set the service address to the correct value for the particular environment at the point of deployment without having to change the orchestration or create some custom mechanism.

In this case, you would simply map the custom endpoint Url parameter to the RESTCaller restUrl argument, since the value you want for the server is set at the time of deployment.

Use Case #3: Using the Same Server with Different Resources Using a Resource Path

Another use case is where a REST service provides access to a number of different resources. For example, these can be collections of resources, such as an initial resource that returns a list of states as follows:

http://server:port/states

With additional resources that return a specific set of data values concerning San Francisco, such as the following:

http://server:port/states/CA/cities/SanFrancisco

You could use an orchestration step to calculate a particular resource path depending on some separately provided value. For example you might pass the values, state = CA and city = SanFrancisco to the orchestration through its event structure or some other means. You could add an orchestration step to calculate the URL to pass to the REST service, taking the base URL from the custom endpoint as follows:

http://server:port/resources/states

and constructing the resource path from the data given and appending it to the URL provided by the custom endpoint as follows:

CA/cities/SanFrancisco

Finally, you would pass the following constructed URL to the RESTCaller restUrl parameter.

http://server:port/resources/states/CA/cities/SanFrancisco

Use Case #4: Using the Same Server with Different Resources Using Query Strings

Some REST services use the HTTP query string to provide additional ways of selecting the resource. You can append these query parameters to the URL as a properly-formatted HTTP query and map them to the RESTCaller restUrl parameter or you can provide them as an array of key-value structures using the RESTCaller params argument, leaving RESTCaller to append the query string.

For more information on RESTCaller, refer to Calling RESTful Web Services from an Orchestration Workflow.