Integrations

An integration is a backend that an API's methods or routes call. To create one, open the API from APIs, choose Integrations in the API editor's section list, then New Integration.

1. Under Backend, pick a Type. HTTP proxy is selected to start with.
2. Pick a Connection: Internet, the default, or Private connector.
3. For an HTTP type, type the backend address in URI template.
4. Optional: set the Timeout, the Security options and, for some protocols, the mapping or caching options.
5. Optional: under Notes, write a Description.
6. Choose Create Integration.

Owners, Admins and Managers can manage integrations. Members see "Access unavailable" in the Integrations section.

The Type of an integration decides what Pods does with a request. Which types an API can use depends on its protocol, and Pods refuses a type the protocol doesn't support.

• HTTP proxy: forwards the request to the backend address as it is, and returns the backend's response. Works with REST, HTTP and WebSocket APIs.
• HTTP (mapped): calls the backend address, with the request and response shaped by mappings and templates on each method. Works with REST and WebSocket APIs.
• Mock: answers without calling any backend. The status code comes from statusCode in the method's request template (200 when there's none), and the integration responses build the rest. Works with REST and WebSocket APIs.

An HTTP API created with a Backend URL starts with an HTTP proxy integration on its $default route. Importing an OpenAPI document that describes integrations also creates them and connects them to their routes or methods, as the Docs, SDKs and OpenAPI guide describes.

The Backend part of the integration dialog sets where Pods sends requests.

• URI template: required for HTTP proxy and HTTP (mapped). It must be an http:// or https:// address, such as https://backend.example.com/{proxy}. It can include {param} path parameters, ${stageVariables.name} and ${request.path.name}.
• Connection: Internet sends requests over the public internet. Private connector sends them through one of the project's connectors, which you pick in Connector; the URI template is then the backend's private address.
• Timeout: drag the slider in steps of 50 ms, from 50 ms up to 29,000 ms for REST and WebSocket APIs or 30,000 ms for HTTP APIs. New integrations start at the maximum.

The Security part of the integration dialog controls the connection to the backend and the credential Pods adds to each call.

• Skip certificate validation: accepts self-signed or mismatched certificates. It's off by default, and meant for testing only.
• SNI override: optional. A hostname to verify instead of the URI's host.
• Backend auth: None, Header, Bearer token, Basic auth, Query parameter, OAuth client credentials, AWS SigV4 or Client certificate.

Every option except None takes a Vault secret: a reference to a secret kept under Security → Secrets, written as secret: followed by the secret's ID. Add @ and a version number to pin one version; without it Pods uses the latest enabled version. Header and Query parameter also need the Header name or Query param name to send it as, such as X-Api-Key.

Pods reads the secret only when it calls the backend. Its value never appears in logs, test output or errors, and it replaces any header of the same name the caller sent. The Security guide covers secrets.

Integrations in an HTTP API have Parameter mapping, which changes the request on its way to the backend and the response on its way back.

• Request mapping: each row has a key and a value. The key is append:, overwrite: or remove: followed by header. or querystring. and a name, such as overwrite:header.X-Name, or overwrite:path to replace the path. The value can come from $request.header., $request.querystring., $request.body., $request.path, $context. or $stageVariables., or be a fixed value in single quotes.
• Response mapping: one table per backend status code. Type a code such as 500 and choose Add status, then add rows such as overwrite:statuscode or append:header.X-Reply, with values from $response.header., $response.body., $context. or $stageVariables..

Pods applies removals first, then overwrites, then appends. REST methods have their own request and response mapping instead, covered in Resources, routes and methods.

Integrations in a REST API have Streaming and caching options.

• Transfer mode: Buffered, the default, or Stream for HTTP proxy integrations. A streamed method can't also use stage caching, response compression or response mapping templates: deploying fails and names the conflict.
• Cache key parameters: one per line, such as method.request.querystring.page or method.request.header.Accept. When a stage caches responses, query parameters outside this list don't change the cache key. For {proxy+} resources, the proxy path is always part of the key.
• Cache namespace: optional, such as v1.

Caching itself is turned on per stage, as the Deployments and stages guide describes. WebSocket integrations have a Template selection expression instead.

The Backends list in the API editor's Integrations section shows each integration's Type, its Target address (or Mock response) and description, its Connection, its Backend auth and its Timeout.

Click a row, or choose Edit in its ⋯ menu, to change it, then choose Save Changes. An integration's settings are shared by every method and route that uses it.

To delete one, choose Delete in its ⋯ menu. Pods asks you to confirm. Routes and methods that used it stop reaching a backend once you deploy, and it can't be undone.