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 ServiceCallout 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 JavaScript object model. For a working sample and code walkthrough, see Implementing HTTP clients in JavaScript.

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 AssignMessage policy is used to populate the request message sent to the remote service. The ExtractVariables policy is used to parse the response and to extract specific content.

The typical ServiceCallout 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 ServiceCallout policy. The policy then sets variables containing the values parsed from the ServiceCallout 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.

Sample

The following ServiceCallout policy submits a request to the Google Geocoding API. The content of the request message is extracted from a variable called GeocodingRequest (which could be populated, for example, by an AssignMessage policy). The response message is assigned to the variable called GeocodingResponse, where it is a available to be parsed, for example, by an ExtractVariables policy or by custom code written in JavaScript or Java.

<ServiceCallout name="GeoCodeClient">
    <Request clearPayload="false" variable="GeocodingRequest" />
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Configuring the ServiceCallout policy

Configure the ServiceCallout policy using the following elements.

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Field Name Description
Request (Optional)
The variable that contains the request message to be sent by the ServiceCallout.
  • 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 ServiceCallout is executed, because clearPayload allocates memory during message processing.
  • The policy returns an error if the request message cannot be resolved by the element or is of an invalid request message type.
Response (Optional)
Output of the ServiceCallout (usually the response message received from the target) that will be 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 returns an error.
  • If this element is not specified, the policy execution does not wait for response to be completely read and executes the message flow steps.
Timeout (Optional)
The time in milliseconds that the ServiceCallout policy will wait for a response from the target before exiting. The default timeout for ServiceCallout is determined by the default HTTP timeout setting for Apigee Edge, which is 120000 milliseconds (120 seconds).
HTTPTargetConnection

Provides transport details such as URL, SSL, HTTP properties. See the TargetEndpoint configuration reference.

Note: You can use flow variables to construct the URL in an HttpTargetConnection element. See the example below. 

Example - ServiceCallout policy

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

Example - Using variables in a URL

<HTTPTargetConnection>
    <Properties/>
    <URL>http://${request.header.targethost}/forecastrss?w=2442047</URL>
</HTTPTargetConnection>

Policy-specific error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The ServiceCallout Policy type defines the following error codes:

Error Code Message
ConnectionInfoMissing Connection information is missing in Step {0}
ExecutionFailed Execution of ServiceCallout {0} failed. Reason: {1}
RequestVariableIsNull ServiceCallout[{0}]: request variable {1} value is null
RequestVariableNotMessageType ServiceCallout[{0}]: request variable {1} value is not of type Message
RequestVariableNotRequestMessageType ServiceCallout[{0}]: request variable {1} value is not of type Request Message
ErrorResponseCode ResponseCode {0} is treated as error
InvalidTimeoutValue Invalid Timeout value {0}
URLMissing JSONToXML[{0}]: Output variable is not available.

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)