Call services or APIs using ServiceCallout

Was this helpful?

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.

(An alternative approach to ServiceCallout is an HTTPClient written in JavaScript using the Apigee JavaScript object model. For a working sample and code walkthrough, see Building a composite service using JavaScript.

Back to top

Policy composition

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:

  1. AssignMessage Policy: Creates a request message, populates HTTP headers, query parameters, sets the HTTP verb, etc.
  2. 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.
  3. 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.

For more information, see Generate or modify messages using AssignMessage and Extract message content using ExtractVariables.

Back to top

Configuring the Service Callout policy

Configure the Service Callout policy using the following elements.

Field Name Description
Request (Optional)
Request variable containing the request message to be sent over a HTTP to a remote target.
  • By default, clearPayload is false.
  • If clearPayload is set to true, the request payload is cleared after the request is sent to the HTTP target.
  • Use the clearPayload option only if the request message is not required after the Service Callout is executed, because clearPayload allocates some memory during message processing.
  • The policy fails to respond if the request message cannot be resolved by the element or is of an invalid request message type.
Response (Optional)
Output of the Service Callout assigned to the response variable.
  • The output generated by the policy is assigned to the variable only when the entire response is read successfully by the policy. If the response message fails for any reason, the policy fails to respond.
  • If this element is not specified, the policy execution does not wait for response to be completely read and executes the message flow steps.
HTTPTargetConnection Provides transport details such as URL, SSL, HTTP properties.
Back to top

Policy schema

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.

Example - ServiceCallout policy

<ServiceCallout name="myPolicy">
    <Request clearPayload="false" variable="myRequest"/>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <Properties/>
        <URL>http://example.com</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Back to top