Service Callout policy

About | Samples | Element reference | Usage notes | Error codes | Related topics

What

The Service Callout policy lets you call to an external service from your API 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 your API's response message, enriching and "mashing up" the data for app end users. Using a Service Callout 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.

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

If you want to include data from a Service Callout response in the request to a backend, attach the policy somewhere in the request. Otherwise, attach where appropriate in the logic of your API flow.

Samples

<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>

This 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 Extract Variables policy or by custom code written in JavaScript or Java. The policy waits 30 seconds for the response from the Google Geocoding API before timing out.

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

This example uses a variable in the URL to dynamically populate the base URL of the target.


Element reference

Following are elements and attributes you can configure on this policy.

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>60000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
</ServiceCallout>

Schemas

See our Github repository samples for the most recent schemas.

<ServiceCallout> attributes

Following are attributes you can set on the parent element. Child element sections in this topic provide their own list of attributes.

Attribute Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
name

The unique machine name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-lanaguage name.

N/A Required

<DisplayName>

A natural-language name that labels the policy in the management UI proxy editor. If omitted, the policy name attribute is used.

<DisplayName>Custom label used in UI</DisplayName>
Default Policy name attribute value.
Presence Optional
Type String

<Request> element

The request that gets sent from the API proxy flow to the external service. The request is contained in a variable.

The policy returns an error if the request message cannot be resolved by the element or is of an invalid request message type.

<Request clearPayload="true" variable="myRequest" />
Default N/A
Presence Optional
Type N/A

Attributes

Attribute Description Default Presence
variable

Name of the variable that will contain the request payload.

NA Optional
clearPayload

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 memory during message processing.

false Optional

<Request>/<IgnoreUnresolvedVariables> element

When set to true, the policy ignores any unresolved variable error in the request.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request> 
Default false
Presence Optional
Type Boolean

<Response> element

When the API proxy expects a response from the Service Callout, enter the name of the variable that will contain the response message received from the target.

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.

 <Response>calloutResponse</Response> 
Default NA
Presence Optional
Type String

<Timeout> element

The time in milliseconds that the Service Callout policy will wait for a response from the target before exiting.

<Timeout>60000</Timeout>
Default 120000 milliseconds (120 seconds), the default HTTP timeout setting for Apigee Edge
Presence Optional
Type Integer

<HTTPTargetConnection> element

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

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

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>
Default N/A
Presence Required
Type N/A

<HTTPTargetConnection>/<URL> element

The URL to the service being called. While the hostname portion of URL must be hard-coded, you can supply the remainder of the URL dynamically with a variable.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>
<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>
Default N/A
Presence Required
Type String

<HTTPTargetConnection>/<SSLInfo> element

The SSL configuration to the backend service. For help on SSL configuration, see Client-SSL to backend servers and "Advanced TargetEndpoint Configuration" in API proxy configuration reference.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>myKeystore</KeyStore>
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>
Default N/A
Presence Optional
Type N/A

<HTTPTargetConnection>/<Properties> element

HTTP transport properties to the backend service. For more information, see Endpoint properties reference.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.streaming.enabled">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>
Default N/A
Presence Optional
Type N/A

Usage notes

The Service Callout is typically used with two other policies: Assign Message and Extract Variables.

  • Request: Assign Message populates the request message sent to the remote service.
  • Response: Extract Variables parses the response and extracts specific content.

The typical Service Callout policy composition involves:

  1. Assign Message policy: Creates a request message, populates HTTP headers, query parameters, sets the HTTP verb, etc.
  2. Service Callout 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. Extract Variables policy: Typically defines a JSONPath or XPath expression that parses the message generated by the Service Callout. The policy then sets variables containing the values parsed from the Service Callout response. 

For a sample policy composition that performs a Service Callout, see the API Platform samples on Github.

For more information, see Assign Message policy and Extract Variables policy.

An alternative approach to Service Callout is an HTTPClient written in JavaScript using the JavaScript object model. For a working sample and code walkthrough, see Implementing HTTP clients in JavaScript.


Error codes

The default format for error codes returned by Policies is:

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

This policy defines the following error codes. For guidance on handling errors, see Fault handling.

Error Code Message
ConnectionInfoMissing Connfaection 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.

Related topics

For working samples of API proxies, see the Samples reference.

 

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?)