ServiceCallout policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation.
info

What

The Service Callout policy lets you call to another service from your API proxy flow. You can make callouts to either an external service (such as an external RESTful service endpoint) or internal services (such as an API proxy in the same organization and environment).

  • In an external use case, you make a callout to a third-party API that's external to your proxy. 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. You can also make a request using the Service Callout policy in the request flow, then pass the information in the response to the TargetEndpoint of the API proxy.
  • In another use case, you call a proxy that's in the same organization and environment as the one you're calling from. For example, you might find this useful when you have a proxy that offers some discrete low-level functionality that one or more other proxies will consume. For example, a proxy that exposes create/read/update/delete operations with a backend data store could be the target proxy for multiple other proxies that expose the data to clients.

The policy supports requests over HTTP and HTTPS.

Samples

Local call to an internal proxy

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

This example creates a callout to a local API proxy (that is, one in the same organization and environment) called data-manager, specifying its proxy endpoint whose name is default.

URL as a variable

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

This example uses a variable in the URL to dynamically populate the URL of the target. The protocol portion of the URL, http://, cannot be specified by a variable. Also, you must use separate variables for the domain portion of the URL and for the rest of the URL.

Google geocoding / define request

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>
http://maps.googleapis.com/maps/api/geocode/json

Instead of using a policy such as Assign Message to create the request object, you can define it directly in the Service Callout policy. In this example, the Service Callout policy sets the values of three query parameters passed to the external service. You can create an entire request message in the Service Callout policy that specifies a payload, encoding type such as application/xml, headers, form parameters, etc.

Here's another example where the request is formed before reaching the Service Callout policy.

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

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

For a complete sample API proxy that uses this example Service Callout, along with the Assign Message and Extract Variables policies, see Using policy composition.

Call target servers

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

This policy uses the LoadBalancer attribute to call target servers and do load balancing across them. In this example, load is distributed across two target servers named "httpbin" and "yahoo". For information about setting up Target Servers for your proxy and configuring load balancing, see Load balancing across backend servers.


About the Service Callout policy

There are many scenarios where you can use a Service Callout policy in your API proxy. For example, you can configure an API proxy to make calls to an external service to deliver geolocation data, customer reviews, items from a partner’s retail catalog, and so on.

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

    For improved performance, you can also cache Service Callout responses, as described in this Apigee Community thread: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
  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.

See Using policy composition for a complete sample API proxy that uses the Service Callout policy along with the Assign Message and Extract Variables policies.

Custom error handling

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>
        <Remove>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

<ServiceCallout> attributes

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

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

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional
Type String

<Request> element

Specifies the variable containing the request message that gets sent from the API proxy to the other service. The variable can be created by a previous policy in the flow, or you can create it inline in the Service Callout policy.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

The syntax for the <Remove>, <Copy>, <Add>, and <Set> tags is the same as for the Assign Message policy.

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

In the simplest example, you pass a variable containing the request message that was populated earlier in the flow of the API proxy:

<Request clearPayload="true" variable="myRequest"/>

Or you can populate the request message sent to the external service in the Service Callout policy itself:

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
Default If you omit the Request element, or any of its attributes, Edge assigns the following default values:

<Request clearPayload="true" variable="servicecallout.request"/>

Let's look at what these default values mean. First, clearPayload=true means that a new request object is created each time the ServiceCallout policy executes. This means that the request and the request URI path are never reused. Second, the default variable name, servicecallout.request, is a reserved name that is assigned to the request if you do not supply a name.

It's important to know about this default name if you are using data masking -- if you omit the variable name, you need to add servicecallout.request to your mask configuration. For example, if you wanted to mask the Authorization header so that it does not appear in Trace sessions, you would add the following to your masking configuration to capture the default name:

servicecallout.request.header.Authorization.

Presence Optional.
Type N/A

Attributes

Attribute Description Default Presence
variable

Name of the variable that will contain the request message.

servicecallout.request Optional
clearPayload

If true, the variable containing the request message is cleared after the request is sent to the HTTP target to free up the memory used by the request message.

Set the clearPayload option to false only if the request message is required after the Service Callout is executed.

true 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

Include this element when the API proxy logic requires the response from the remote call for further processing.

When this element is present, it specifies the name of the variable that will contain the response message received from the external service. The response from the target is assigned to the variable only when the entire response is read successfully by the policy. If the remote call fails for any reason, the policy returns an error.

If this element is omitted, the API proxy does not wait for a response; API Proxy flow execution continues with any subsequent flow steps. Also, to state the obvious, with no Response element, the response from the target is not available for processing by subsequent steps, and there is no way for the proxy flow to detect a failure in the remote call. A common use for omitting the Response element when using ServiceCallout: to log messages to an external system.

 <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. You cannot set this value dynamically at runtime. If the Service Callout hits a timeout, an HTTP 500 is returned, the policy fails, and the API proxy goes into an error state, as described in Handling faults.

<Timeout>30000</Timeout>
Default 55000 milliseconds (55 seconds), the default HTTP timeout setting for Apigee Edge
Presence Optional
Type Integer

<HTTPTargetConnection> element

Provides transport details such as URL, TLS/SSL, and HTTP properties. See the <TargetEndpoint> configuration reference.

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

<HTTPTargetConnection>/<URL> element

The URL to the service being called:

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

You can supply part of the URL dynamically with a variable. However, the protocol portion of the URL, http:// below, cannot be specified by a variable. In the next example, you use a variable to specify the value of a query parameter:

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

Or, set a portion of the URL path with a variable:

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

If you want to use a variable to specify the domain and port of the URL, then use one variable for the domain and port only, and a second variable for any other part of the URL:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>
Default N/A
Presence Required
Type String

<HTTPTargetConnection>/<SSLInfo> element

The TLS/SSL configuration to the backend service. For help on TLS/SSL configuration, see Configuring TLS from Edge to the backend (Cloud and Private Cloud) and "TLS/SSL TargetEndpoint Configuration" in API proxy configuration reference.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <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.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>
Default N/A
Presence Optional
Type N/A

<HTTPTargetConnection>/<LoadBalancer> element

Call one or more target servers and do load balancing on them. See the Call target servers sample in the Samples section. See also Load balancing across backend servers. See also this community post that discusses ways to call target servers from both the Service Callout policy and using Route Rules.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
Default N/A
Presence Optional
Type N/A

<LocalTargetConnection> element

Specifies a local proxy -- that is, a proxy in the same organization and environment -- as the target of service callouts.

To further specify the target, use either the <APIProxy> and <ProxyEndpoint> elements, or the <Path> element.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>
Default N/A
Presence Required
Type N/A

<LocalTargetConnection>/<APIProxy> element

The name of an API proxy that is the target of a local call. The proxy must be in the same organization and environment as the proxy making the call.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

Along with the <APIProxy> element, include the <ProxyEndpoint> element to specify the name of the proxy endpoint that should be targeted for the call.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection> 
Default N/A
Presence Required
Type String

<LocalTargetConnection>/<ProxyEndpoint> element

The name of the proxy endpoint that should be the target of calls. This is a proxy endpoint in the API proxy specified with the <APIProxy> element.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
Default N/A
Presence Optional
Type N/A

<LocalTargetConnection>/<Path> element

A path to the endpoint that is being targeted. The endpoint must refer to a proxy in the same organization and environment as the proxy making the call.

Use this instead of a <APIProxy>/<ProxyEndpoint> pair when you don't know -- or can't rely on -- the proxy name. The path might be a reliable target.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>
Default N/A
Presence Optional
Type N/A

Schemas

Flow variables

Flow variables enable dynamic behavior of policies and Flows at runtime, based on HTTP headers, message content, or Flow context. The following predefined Flow variables are available after a Service Callout policy executes. For more information about Flow variables, see Variables reference.

Service Callouts have their own request and response, and you can access that data through variables. Because the main message is using the request.* and response.* variable prefixes, use the myrequest.* and calloutResponse.* prefixes (the defaults in the Service Callout configuration) to get message data specific to the Service Callout. The first example in the following table shows how you'd get HTTP headers in the Service Callout.

Variable Description

Following is an example of getting Service Callout request and response headers similar to how you would get headers from the main request and response.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

where calloutResponse is the variable name for the Response in the Service Callout, and myRequest is the variable name for the Request. For example:

calloutResponse.header.Content-Length

returns the Content-Length header of the Service Callout response.

Scope: From the Service Callout forward
Type: String
Permission: Read/Write

A message header in the Service Callout request or response. For example, if the API proxy target is http://example.com, and the Service Callout target is http://mocktarget.apigee.net, these variables are the headers for the callout to http://mocktarget.apigee.net.

servicecallout.requesturi

Scope: From the Service Callout request forward
Type: String
Permission: Read/Write

The TargetEndpoint URI for a ServiceCallout policy. The URI is the TargetEndpoint URL without the protocol and domain specification.

servicecallout.{policy-name}.target.url

Scope: From the Service Callout request forward
Type: String
Permission: Read/Write

The target URL for a the Service Callout.

calloutResponse.content

where calloutResponse is the <Response>variable name in the Service Callout configuration.

Scope: From the Service Callout response forward
Type: String
Permission: Read/Write

The response body from the Service Callout.

servicecallout.{policy-name}.expectedcn

Scope: From the Service Callout request forward
Type: String
Permission: Read/Write

The expected Common Name of the TargetEndpoint as referred to in a ServiceCallout policy. This is meaningful only when the TargetEndpoint refers to a TLS/SSL endpoint.

servicecallout.{policy-name}.failed

Scope: From the Service Callout response forward
Type: Boolean
Permission: Read/Write

Boolean indicating if the policy succeeded, false, or failed, true.

Errors

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.servicecallout.ExecutionFailed 500

This error can occur when:

  • the policy is asked to handle input that is malformed or otherwise invalid.
  • the backend target service returns an error status (by default, 4xx or 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 The Request variable specified in the policy is not of type Message. For example, if it's a string or other non-message type, you'll see this error.
steps.servicecallout.RequestVariableNotRequestMessageType 500 The Request variable specified in the policy is not of type Request Message. For example, if it's a Response type, you'll see this error.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
URLMissing The <URL> element inside <HTTPTargetConnection> is missing or empty.
ConnectionInfoMissing This error happens if the policy does not have an <HTTPTargetConnection> or <LocalTargetConnection> element.
InvalidTimeoutValue This error happens if the <Timeout> value is negative or zero.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "RequestVariableNotMessageType"
servicecallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. servicecallout.SC-GetUserData.failed = true

Example error response

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: 
            request variable data_str value is not of type Message"
   }
}

Example fault rule

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

Related topics