This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The ServiceCallout 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).

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

• 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 andmashing up the data for app end users. You can also make a request using the ServiceCallout 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

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

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

<ServiceCalloutname="ServiceCallout-GeocodingRequest1"><DisplayName>Inlinerequestmessage</DisplayName><Requestvariable="authenticationRequest"><Set><QueryParams><QueryParamname="address">{request.queryparam.postalcode}</QueryParam><QueryParamname="region">{request.queryparam.country}</QueryParam><QueryParamname="sensor">false</QueryParam></QueryParams></Set></Request><Response>GeocodingResponse</Response><Timeout>30000</Timeout><HTTPTargetConnection><URL>https://maps.googleapis.com/maps/api/geocode/json</URL></HTTPTargetConnection></ServiceCallout>

<ServiceCalloutname="ServiceCallout-GeocodingRequest2"><RequestclearPayload="false"variable="GeocodingRequest"/><Response>GeocodingResponse</Response><Timeout>30000</Timeout><HTTPTargetConnection><URL>https://maps.googleapis.com/maps/api/geocode/json</URL></HTTPTargetConnection></ServiceCallout>

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

About the ServiceCallout policy

There are many scenarios where you can use a ServiceCallout 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: AssignMessage and ExtractVariables.

• Request: AssignMessage populates the request message sent to the remote service.

• Response: ExtractVariables parses the response and extracts specific content.

  Note: The request and response message headers in a ServiceCallout are already available as variables, as described in theFlow Variables section. You do not need to extract those with the ExtractVariables policy.

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 AssignMessage 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 ServiceCallout responses, as described inHow can I store the results of the ServiceCallout policy in cache? and later, retrieve it from cache?

3. ExtractVariables policy: Typically defines a JSONPath or XPath expression that parses the message generated by the ServiceCallout. The policy then sets variables containing the values parsed from the ServiceCallout response.

Custom error handling

Element reference

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

<ServiceCalloutasync="false"continueOnError="false"enabled="true"name="Service-Callout-1"><DisplayName>CustomlabelusedinUI</DisplayName><RequestclearPayload="true"variable="myRequest"><IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables><Remove><StatusCode/><Path/><Version/><Verb/></Remove><Copy><StatusCode/><Path/><Version/><Verb/></Copy><Add><Headers/><QueryParams/><FormParams/></Add><Set><Headers/><QueryParams/><FormParams/><Payload/><StatusCode/><Path/><Version/><Verb/></Set></Request><Response>calloutResponse</Response><Timeout>30000</Timeout><HTTPTargetConnection><URL>http://example.com</URL><LoadBalancer/><SSLInfo/><Properties/><Authentication><HeaderNameref="{variable}">STRING</HeaderName><GoogleAccessToken><Scopes><Scope>https://www.googleapis.com/auth/cloud-platform</Scope></Scopes><LifetimeInSecondsref="{variable}">3600</LifetimeInSeconds></GoogleAccessToken></Authentication><Authentication><HeaderNameref="{variable}">STRING</HeaderName><GoogleIDToken><Audienceref="{variable}"useTargetUrl="BOOLEAN">{hostname}</Audience><IncludeEmailref="{variable}">true</IncludeEmail></GoogleIDToken></Authentication></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:

<DisplayName> element

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

<DisplayName>Policy Display Name</DisplayName>

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

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

The syntax for the<Remove>,<Copy>,<Add>, and<Set> tags is the same as for theAssignMessage 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:

<RequestclearPayload="true"variable="myRequest"/>

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

<Request><Set><Headers><Headername="Accept">application/json</Header></Headers><Verb>POST</Verb><PayloadcontentType="application/json">{"message":"my test message"}</Payload></Set><IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables></Request>

Attributes

<Request>/<IgnoreUnresolvedVariables> element

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

<RequestclearPayload="true"variable="myRequest"><IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables></Request>

<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 noResponse 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 theResponse element when using ServiceCallout: to log messages to an external system.

 <Response>calloutResponse</Response>

<Timeout> element

The time in milliseconds that the ServiceCallout policy will wait for a response from the target. You cannot set this value dynamically at runtime. If the ServiceCallout hits a timeout, an HTTP 500 is returned, the policy fails, and the API proxy goes into an error state, as described inHandling faults.

<Timeout>30000</Timeout>

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

GeneratesGoogle OAuth 2.0 or Google-issuedOpenID Connect tokens to make authenticated calls to Google services and custom services running on certain Google Cloud products, such asCloud Functions andCloud Run. Use of this element requires setup and deployment steps described inUsing Google authentication. Withproper setup, the policy creates an authentication token for you and adds it to the service request.

The child elements,GoogleAccessToken andGoogleIDToken, let you configure the policy to generate either Google OAuth or OpenID Connect tokens. You need to pick one of these child elements depending on the type of service you wish to call.

The ServiceCallout policy only supports calling HTTP-based services.

TheAuthentication element uses the following syntax:

<ServiceCallout>...<HTTPTargetConnection><Authentication><HeaderNameref="FLOW_VARIABLE">STRING</HeaderName><GoogleAccessToken><Scopes><Scope>SCOPE</Scope>...</Scopes><!--NOTE:ThedefaultvalueforLifetimeInSecondsis3600.Changethedefaultonlyifyouwanttolimittheriskofleakedaccesstokensorimproveperformance.--><LifetimeInSecondsref="{variable}">INTEGER</LifetimeInSeconds></GoogleAccessToken>--OR--<HeaderNameref="FLOW_VARIABLE">STRING</HeaderName><GoogleIDToken><Audienceref="{variable}"useTargetUrl="BOOLEAN">STRING</Audience><IncludeEmailref="{variable}">BOOLEAN</IncludeEmail></GoogleIDToken></Authentication></HTTPTargetConnection></ServiceCallout>

<Authentication>  <GoogleAccessToken>    <Scopes>      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>    </Scopes>  </GoogleAccessToken></Authentication>

<Authentication>  <GoogleIDToken>      <Audience>https://httpserver0-bar.run.app</Audience>      <IncludeEmail>false</IncludeEmail>  </GoogleIDToken></Authentication>

  <Authentication>    <HeaderName>X-Serverless-Authorization</HeaderName>    <GoogleAccessToken>      <Scopes>        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>      </Scopes>    </GoogleAccessToken>  </Authentication>

<Authentication><GoogleAccessToken><Scopes><Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope></Scopes><LifetimeInSecondsref="variable">3600</LifetimeInSeconds></GoogleAccessToken></Authentication>

Attributes

None.

HeaderName child element

By default, when an Authentication configuration is present, Apigee generates a bearer token and injects it into theAuthorization header in the message sent to the target system. TheHeaderName element allows you to specify the name of a different header to hold that bearer token. This feature is particularly useful when the target is a Cloud Run service that uses theX-Serverless-Authorization header. TheAuthorization header, if present, is left unmodified and also sent in the request.

TheHeaderName element uses the following syntax:

<ServiceCallout>...  <Authentication>    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>    <GoogleAccessToken>      ...    </GoogleAccessToken>  </Authentication>  ...</ServiceCallout>

<Authentication>  <HeaderName>X-Serverless-Authorization</HeaderName>  <GoogleAccessToken>    <Scopes>      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>    </Scopes>  </GoogleAccessToken></Authentication>

<Authentication><HeaderNameref='my-variable'>X-Serverless-Authorization</HeaderName><GoogleAccessToken><Scopes><Scope>https://www.googleapis.com/auth/cloud-platform</Scope></Scopes></GoogleAccessToken></Authentication>

GoogleAccessToken child element

GeneratesGoogle OAuth 2.0 tokens to make authenticated calls to Google services. Google OAuth tokens can be used to call many kinds of Google services, such asCloud Logging andSecret Manager.

TheGoogleAccessToken element uses the following syntax:

<ServiceCallout>...  <Authentication>    <GoogleAccessToken>      <Scopes>        <Scope>SCOPE_1</Scope>        ...      </Scopes>      <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing      the default unless you want to limit the risk of leaked access tokens or improve performance. -->      <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>    </GoogleAccessToken>  </Authentication>  ...</ServiceCallout>

<Authentication>  <GoogleAccessToken>    <Scopes>      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>    </Scopes>  </GoogleAccessToken></Authentication>

<ServiceCallout name="ServiceCallout-sm">  <Response>SecretManagerResponse</Response>  <Timeout>30000</Timeout>  <HTTPTargetConnection>    <Authentication>      <GoogleAccessToken>        <Scopes>          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>        </Scopes>      </GoogleAccessToken>    </Authentication>    <URL>      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id    </URL>  </HTTPTargetConnection></ServiceCallout>

<ServiceCallout name="ServiceCallout-CloudRun">  <Response>CloudRunResponse</Response>  <Timeout>30000</Timeout>  <HTTPTargetConnection>    <Authentication>      <GoogleIDToken>        <Audience>https://cloudrun-hostname.a.run.app/test</Audience>      </GoogleIDToken>    </Authentication>    <URL>https://cloudrun-hostname.a.run.app/test</URL>  </HTTPTargetConnection></ServiceCallout>

Scopes child element

Identifies the scopes to be included in the OAuth 2.0 access token. For more information, see OAuth 2.0 Scopes for Google APIs. You can add one or more<Scope> child elements under this element.

Scope child element

Specifies a valid Google API scope. For more information, see OAuth 2.0 Scopes for Google APIs.

LifetimeInSeconds child element

Specifies the lifetime duration of the access token in seconds.Note:The default value for LifetimeInSeconds is 3600. We do not recommend changing the default unless you want to limit the risk of leaked access tokens or improve performance.

GoogleIDToken child element

Generates Google-issuedOpenID Connect tokens to make authenticated calls to Google services.

TheGoogleIDToken element uses the following syntax:

<ServiceCallout>...<Authentication><GoogleIDToken><Audienceref="{variable}"useTargetUrl="BOOLEAN">STRING</Audience><IncludeEmailref="{variable}">BOOLEAN</IncludeEmail></GoogleIDToken></Authentication></ServiceCallout>

<Authentication>  <GoogleIDToken>      <Audience>https://httpserver0-bar.run.app</Audience>      <IncludeEmail>true</IncludeEmail>  </GoogleIDToken></Authentication>

Audience child element

The audience for the generated authentication token, such as the API or account that the token grants access to.

If the value ofAudience is empty or theref variable does not resolve to a valid value, anduseTargetUrl istrue, then the URL of the target (excluding any query parameters) is used as the audience. By default,useTargetUrl isfalse.

<Audience>explicit-audience-value-here</Audience>or:<Audienceref='variable-name-here'/>or:<Audienceref='variable-name-here'useTargetUrl='true'/>or:<AudienceuseTargetUrl='true'/>

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

<HTTPTargetConnection>/<SSLInfo> element

The TLS/SSL configuration to the backend service. For help on TLS/SSL configuration, seeOptions for configuring TLS and "TLS/SSL TargetEndpoint Configuration" inAPI 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>

<HTTPTargetConnection>/<Properties> element

HTTP transport properties to the backend service. For more information, seeEndpoint 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>

<HTTPTargetConnection>/<LoadBalancer> element

Call one or more target servers and do load balancing on them. See theCall target servers sample in theSamples section. See alsoLoad balancing across backend servers. See alsoTarget Endpoint/Server callout that discusses ways to call target servers from both the ServiceCallout policy and using Route Rules.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>

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

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

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

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

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 ServiceCallout policy executes. For more information about Flow variables, seeFlow variables reference.

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

Errors

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

Runtime errors

These errors can occur when the policy executes.

Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service          account identity, but one was not provided with the request.

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

Example error response

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

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

• Generate or modify messages:AssignMessage policy
• Extract variables:ExtractVariables policy
• Variables:Flow variables reference
• TLS/SSL configuration
  • Options for configuring TLS
  • "TLS/SSL TargetEndpoint Configuration" inAPI proxy configuration reference
• HTTP transport properties:Endpoint properties reference
• Alternative to ServiceCallout: HTTPClient written in JavaScript, seeJavaScript object model.