APIs are at their best when they are combined to create composite services that bundle resources from multiple services and API providers. One way of bundling API calls is to configure a ServiceCallout policy within a request or response flow.
A typical use case involves a service callout from a response flow to a third-party API (external service). The response from the third-party API is parsed and inserted in the response message to the requesting app.The data returned from the backend service is enriched with the data obtained from the third-party API, providing the end users of the app with data 'mashed up' from multiple services. Using a ServiceCalout policy, you can configure an API proxy to make multiple API calls to deliver relevant geolocation data, customer reviews, items from a partner’s retail catalog, and so on.
Policy composition is an important concept to understand when configuring ServiceCallouts. Policy composition is the definition of a sequence of policies that work together to perform a task. The ServiceCallout is usually used with two other policy types, AssignMessage and ExtractVariables. The Assign Message policy is used to populate the request message sent to the remote service. The Extract Variables policy is used to parse the response and to extract specific content.
The typical Service Callout policy composition involves:
- AssignMessage Policy: Creates a request message, populates HTTP headers, query parameters, sets the HTTP verb, etc.
- ServiceCallout Policy: References a message created by the Assign Message policy, defines a target URL for the external call, and defines a name for the response object that the target service returns.
- ExtractVariables Policy: Typically defines a JSONPath or XPath expression that parses the message generated by the preceding Service Callout policy. The policy then sets variables containing the values parsed from the Service Callout response.
For a sample policy composition that performs a ServiceCallout, see the API Platform samples on Github.
Configure the Service Callout policy using the following elements.
Request variable containing the request message to be sent over a HTTP to a remote target.
Output of the Service Callout assigned to the response variable.
|HTTPTargetConnection||Provides transport details such as URL, SSL, HTTP properties.|
Each policy must conform to a policy schema. All policy constructs such as elements and attributes mentioned above are defined in a schema. To download the schema, click here.