http-callout.md

description
This page provides the technical details of the HTTP Callout policy

HTTP Callout

Overview

You can use the callout-http policy to invoke an HTTP(S) URL and place a subset or all of the content in one or more variables of the request execution context.

This can be useful if you need some data from an external service and want to inject it during request processing.

The result of the callout is placed in a variable called calloutResponse and is only available during policy execution. If no variable is configured, the result of the callout is no longer available.

Functional and implementation information for the callout-http policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 proxy APIs. It cannot be applied to v4 message APIs. {% endhint %}

{% tabs %} {% tab title="Proxy API example" %} Sample policy configuration:

"policy-http-callout": {
    "method": "GET",
    "url": "https://api.gravitee.io/echo",
    "headers": [ {
        "name": "X-Gravitee-Request-Id",
        "value": "{#request.id}"
    }],
    "variables": [{
        "name": "my-server",
        "value": "{#jsonPath(#calloutResponse.content, '$.headers.X-Forwarded-Server')}"
    }]
}

{% endtab %} {% endtabs %}

Configuration

Phases

The phases checked below are supported by the callout-http policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	true	onResponse	true
onRequestContent	true	onMessageRequest	false
onResponseContent	true	onMessageResponse	false

Options

The callout-http policy can be configured with the following options:

Property	Required	Description	Type	Default
method	true	HTTP Method used to invoke URL	HTTP method	GET
useSystemProxy	true	Use the system proxy configured by your administrator	boolean	false
url	true	URL invoked by the HTTP client (support EL)	URL	-
headers	true	List of HTTP headers used to invoke the URL (support EL)	HTTP Headers	-
body	true	The body content send when calling the URL (support EL)	string	-
fireAndForget	true	Make the http call without expecting any response. When activating this mode, context variables and exit on error are useless.	boolean	false
variables	true	The variables to set in the execution context when retrieving content of HTTP call (support EL)	List of variables	-
exitOnError	true	Terminate the request if the error condition is true	boolean	false
errorCondition	true	The condition which will be verified to end the request (support EL)	string	{#calloutResponse.status >= 400 and #calloutResponse.status ⇐ 599}
errorStatusCode	true	HTTP Status Code sent to the consumer if the condition is true	int	500
errorContent	true	The body response of the error if the condition is true (support EL)	string

System Proxy

If the option useSystemProxy is checked, proxy information will be read from JVM_OPTS or from the gravitee.yml file if JVM_OPTS is not set. The system properties are as follows:

Property	Required	Description
system.proxy.host	true	Proxy Hostname or IP
system.proxy.port	true	The proxy port
system.proxy.type	true	The type of proxy (HTTP, SOCK4, SOCK5)
system.proxy.username	false	Username for proxy authentication if any
system.proxy.password	false	Password for proxy authentication if any

HTTP client proxy options

# global configuration of the http client
system:
  proxy:
    type: HTTP
    host: localhost
    port: 3128
    username: user
    password: secret

Compatibility matrix

The following is the compatibility matrix for APIM and the callout-http policy:

Plugin Version	Supported APIM versions
2.x+	3.18+
1.15.x+	3.15.x to 3.17.x
1.13.x to 1.14.x	3.10.x to 3.14.x
Up to 1.12.x	Up to 3.9.x

Errors

HTTP status code	Error template key
500	An error occurred while invoking URL

You can override the default response provided by the policy with the response templates feature. These templates must be defined at the API level with the APIM Console Proxy > Response Templates function.

The error keys sent by this policy are as follows:

Key	Parameters
CALLOUT_EXIT_ON_ERROR	-
CALLOUT_HTTP_ERROR	-

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-callout-http/blob/master/CHANGELOG.md" %}