Deployments & stages

Deploying takes a snapshot of the API's draft, called a deployment, and points a stage at it. Callers only see changes once they're deployed. Owners, Admins and Managers can deploy.

1. Open the API from APIs and choose Deploy at the top of the API editor.
2. Optional: in Description, write release notes for the deployments list, up to 1,024 characters.
3. In Stage, pick an existing stage or type a new name, such as prod.
4. Choose Deploy.

A new stage name creates the stage, serving this deployment. An existing stage switches to it straight away. If the draft can't be deployed as it is, the dialog shows why and nothing changes.

Stage names are 1 to 128 letters, digits, _ and -. HTTP and WebSocket APIs can also use $default. Pods allows one deployment every 2 seconds per API.

Choose Deployments in the API editor's section list to see the API's deployments, newest first. Each row shows the deployment's short ID and digest, its Description, when it was Created, and which stages it's Serving.

Each row's ⋯ menu has:

• Deploy to each stage, such as Deploy to prod. Pods asks you to confirm, then the stage's live traffic switches to that deployment at once. Use it to go back to an earlier deployment too.
• Compare, to see what changed between two deployments.
• Copy deployment ID.

Deployments can't be edited, because each one is a fixed snapshot. The list shows 25 a page; switch to 10, 50 or 100 at the bottom.

To compare two deployments, choose Compare in one deployment's ⋯ menu in the API editor's Deployments section, then Compare in another's. The first one is marked Comparing while you pick the second.

Changes then lists each setting that differs, with its old value and its new value, up to 50 changes. "No differences" means the two snapshots are identical. Choose Clear to close the comparison.

A stage is a named environment, such as dev or prod, that serves one deployment at its own invoke URL: the address callers use. You create a stage by deploying to a new stage name.

Choose Stages in the API editor's section list to see each stage, which deployment it's Serving (or No deployment yet), and its Invoke URL, with a copy icon beside it. A stage Pods redeploys on every draft change carries an Auto-deploy badge.

Click a stage, or choose Open in its ⋯ menu, to open it. Its tabs are Settings, Cache, Throttling, Logs & tracing and History. All stages goes back to the list.

Stage variables are name and value pairs that integrations and mapping templates read on that stage, so one deployment can call a different backend on each stage. For example, an integration's URI can use ${stageVariables.backend}.

To set them, open the stage from the API editor's Stages section and edit Variables (JSON) on its Settings tab, such as {"backend": "api.example.com"}. Then choose Save Changes.

• Names are up to 64 letters, digits and underscores.
• Values are up to 512 characters of letters, digits and - . _ ~ : / ? # & = ,.
• A stage holds up to 100 variables.

Owners, Admins and Managers can change stage variables; others see them read-only.

A stage's History tab lists every time it moved to a different deployment: when it was Created, each Deploy, Rollback and Auto-deploy, which deployment it moved from and to, and when. You can also open it with Deployment history in the stage's ⋯ menu. Reload fetches it again.

To undo a change, choose Roll back to previous in that entry's ⋯ menu. Pods asks you to confirm, then points the stage back at the deployment it served before that change, and live traffic switches immediately. Owners, Admins and Managers can roll back.

A REST API stage can cache GET responses for up to an hour. Open the stage from the API editor's Stages section and choose its Cache tab.

• Enable cache: off by default.
• Capacity (GB): 0.5, 1.6, 6.1, 13.5, 28.4, 58.2, 118 or 237.
• Default TTL (seconds): from 0 to 3600, 300 to start with.
• Encrypt cached responses: stores cached bodies encrypted.
• Require authorization to bypass the cache: on by default, so only authorized callers can force a fresh response with Cache-Control: max-age=0. When an unauthorized caller tries to bypass sets what happens to the rest: reject with 403, serve from cache with a warning header (the default), or serve from cache silently.
• Per-method overrides: choose Add Override and type a method such as /pets/GET, or */* for all, with its own TTL and Cache switch.

Choose Save Changes. Responses to authenticated requests are cached per caller. To empty the cache, choose Flush Cache, type the stage name and confirm; it can't be undone. Owners, Admins and Managers can change and flush the cache.

A stage's Throttling tab limits how many requests it accepts. Open the stage from the API editor's Stages section.

• Default rate (requests/sec) and Default burst: the stage-wide limits. Set both, or leave both empty for no stage limit. A rate or burst of 0 blocks all traffic.
• Method overrides (JSON) on REST APIs, or Route overrides (JSON) on HTTP and WebSocket APIs: up to 20 limits for single methods or routes, such as {"/pets/GET": {"rateLimit": 50, "burstLimit": 100}}.

Choose Save Throttling. Gateways apply it within a minute. A stage's limits can't exceed the project's own throttle. Owners, Admins and Managers can change throttling. Limits per caller come from usage plans, covered in Usage plans and API keys.

A stage's Logs & tracing tab sets what Pods records for its traffic. Open the stage from the API editor's Stages section.

• Access logging: writes one line per request. The Format must include $context.requestId or $context.extendedRequestId; start from the CLF or JSON preset, and check the Preview.
• Destinations: comma separated. pods sends lines to Pods' own log search, and a log export's ID sends them there too.
• Execution logging level: Off, Errors only or Info.
• Data trace: also stores request and response bodies, cut to 1 KB. Only Owners, Admins and Managers can view them.
• Detailed metrics: records metrics per route for this stage.
• Tracing: samples one request a second plus 5% of the rest.

Choose Save Changes. Owners, Admins and Managers can change these settings. Logs, traces and exports are covered in Monitoring.