APIs

To create an API, choose APIs in the Pods sidebar, then New API. Only Owners and Admins see the button.

1. Pick a protocol: REST, HTTP or WebSocket. REST is selected to start with.
2. In Name, type up to 128 characters. Names are unique within the project, so Pods refuses a name another API already uses.
3. Optional: write a Description of up to 1,024 characters.
4. Optional, for an HTTP API: in Backend URL, type an http:// or https:// address.
5. Choose Create API.

The new API appears in the list with its own API ID. A REST API starts with an empty root resource, /.

When you give an HTTP API a Backend URL, Pods also sets it up to serve traffic straight away: it adds a $default route that forwards every request to that address, creates a $default stage with auto-deploy turned on, and deploys the API to it.

Every API has one protocol, chosen when you create it. It can't be changed later: to switch, create a new API. The protocol decides what you build in the API editor.

• REST: full-featured APIs built from a tree of resources and the methods on each path, with models, gateway responses, documentation, SDKs and agent tools. Only REST APIs can use the EDGE and PRIVATE endpoint types and resource policies.
• HTTP: lighter APIs built from routes, such as GET /pets, with their own CORS settings.
• WebSocket: APIs that keep a two-way connection open, built from routes such as $connect, $disconnect and your own route keys, with models.

API keys and usage plans work with REST and WebSocket APIs.

The Resources, routes and methods guide covers building each kind.

What you edit in the API editor is the API's draft: its resources or routes, integrations, authorizers and settings. Callers never reach the draft directly.

• A deployment is an immutable snapshot of the draft, taken when you deploy.
• A stage, such as prod, is a named environment that serves one deployment at its own invoke URL.

So a change to the draft reaches callers only once you deploy it to a stage. The exception is a stage with auto-deploy on, such as the $default stage Pods creates for an HTTP API given a Backend URL: Pods redeploys it about a second after each change to the draft. If the draft has an error, auto-deploy leaves live traffic as it was.

The Deployments and stages guide covers deploying, stages and rolling back.

Choose APIs in the sidebar to see every API in the project. The figures across the top count Total APIs and how many are REST, HTTP and WebSocket. Search and filters don't change them.

Each row shows the API's name and description, its Protocol, its Endpoint type, its API ID and when it was last Updated. Narrow the list with the Protocol filter, or search by name, description or API ID.

The list shows 25 APIs a page. Switch to 10, 50 or 100 at the bottom.

Click a row to open the API in the API editor. Each row's ⋯ menu has Open, Copy API ID and, for Owners and Admins, Delete.

Click an API in the list to open it in the API editor. The header shows the API's name, its protocol and endpoint type, and its API ID. All APIs, at the top left, goes back to the list.

The editor's sections are listed beside it, in groups. Click one to open it, or type in Search screens to find it. Which sections appear depends on the protocol.

• Overview: a summary of the API and its stages.
• Build: Resources (REST), Routes (HTTP and WebSocket), Integrations, Authorizers, Models (REST and WebSocket), CORS (HTTP) and Gateway Responses (REST).
• Release: Deployments and Stages.
• Observe: Monitoring, the API's requests, latency and errors.
• Distribute: Docs, SDKs and Agent Tools (REST), and Import / Export (REST and HTTP).
• Configure: Settings.

Deploy, at the top right, snapshots the draft onto a stage. Owners, Admins and Managers see it.

An API opens on its Overview section in the API editor. The figures across the top show the Protocol and endpoint type, how many Stages it has and how many of them serve a deployment, whether its Default endpoint is on, and its Version label.

At a glance lists the API ID, the IP address type, what callers get for a path that doesn't exist (Missing route) and the description. Copy API ID copies the ID.

Stages lists each stage with its invoke URL, the address callers use. A stage can carry an Auto-deploy or Canary badge. Click the copy icon beside an invoke URL to copy it, or choose Manage to open the Stages section. Before anything is deployed, the box offers to open Deployments instead.

Next steps has three shortcuts, in the order you build an API: Resources (or Routes), Integrations and Deploy, which opens Deployments.

The Settings section of the API editor holds the API's own settings. Only Owners and Admins can change them. Make your changes, then choose Save Changes.

• Name (up to 128 characters), Version label (up to 64, such as v1) and Description. The protocol is fixed.
• Endpoint type: REGIONAL, the default, or EDGE or PRIVATE for a REST API. A PRIVATE API is reachable only through a Pods connector in ingress mode, with a resource policy that allows it.
• IP address type: IPv4 only, the default, or Dual-stack (IPv4 + IPv6).
• Disable default endpoint: stops serving the API at its invoke URLs from the next deployment, so it's reached only through custom domains. Mutual TLS needs it on.

REST APIs also have Request handling:

• API key source: HEADER, the default, or AUTHORIZER.
• Missing route behavior: 403 Missing Authentication Token (AWS), the default, or 404 Not Found.
• Binary media types: one per line, such as image/png.
• Minimum compression size: in bytes, from 0 to 10485760. Leave it empty to turn compression off.

Further down are the resource policy (REST) and tags. Managers and Members see "Access unavailable" here instead.

Tags are key and value pairs that label an API. They're in the Tags card of the API editor's Settings section. Choose Add Tag, type a Key and a Value, then choose Add Tag again.

• Keys are 1 to 128 characters of letters, numbers, spaces and _ . : / = + - @. Keys that start with aws: or pods: are reserved.
• Values are up to 256 characters, and can be empty.
• An API holds up to 50 tags. Each key is unique, so saving an existing key replaces its value.

Click a tag to change its value. To remove one, choose Remove in its ⋯ menu and confirm. Each change saves straight away.

Deleting an API removes its draft and everything defined under it, and its stages stop serving traffic. It can't be undone in Pods. Only Owners and Admins can delete an API.

In the API editor, open Settings and choose Delete API under Danger zone. Type the API's name exactly to turn on Delete, then choose it. Pods returns to the API list.

You can also choose Delete in the API's ⋯ menu in the list. Pods asks you to confirm there too, without typing the name.