Resources, routes & methods

A REST API is a tree of resources, one per path segment, with methods such as GET and POST on each. Open the API from APIs, then choose Resources in the API editor's section list. Every REST API starts with the root resource, /.

1. In Resource tree, choose New Resource.
2. In Parent, pick the resource to add under. It starts as the one selected in the tree.
3. In Path part, type one segment: a literal such as pets, a path parameter such as {id}, or a catch-all {proxy+}.
4. Choose Create Resource.

Each parent holds one resource per path part, and at most one variable part ({id} or {proxy+}). A {proxy+} resource matches everything beneath it, so it can't have children.

To add a method, click a resource in the tree, pick GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS or ANY next to Methods, then choose Add Method. An exact method wins over ANY, and HEAD never falls back to GET. Until a resource has a method, requests to it get 403 Missing Authentication Token.

Owners, Admins and Managers can add and delete resources and methods.

Click a method under Methods in the API editor's Resources section to open its details beneath. Each row shows its authorization, API key required when the method needs one, and its operation name.

• Authorization: who can call the method. The Authorizers and resource policies guide covers it.
• Method request: under Request parameters, declare the headers, query strings and path parameters the method takes, such as method.request.querystring.page, and mark each one required or optional. Under Request models, add a content type such as application/json and pick the model its body follows: Empty, Error or one of the API's models. $default applies when no other content type matches. Choose Save Method Request.
• Method responses: the status codes the method returns. Click a status code, or type a new one, then declare its Response headers, such as method.response.header.X-Reply, and its Response models. Choose Save for that code, such as Save 200 Response.

Each card saves on its own button. Models themselves are covered in Models, CORS and gateway responses.

A method's Integration request card sets how an incoming call becomes the request to its backend. It appears in the method's details once the method has an integration; until then the Integration card says none is attached. The Integrations guide covers the backends themselves.

• Request mapping: set a backend header, query string or path value, such as integration.request.header.X-Target, from method.request.*, context.*, stageVariables.* or a fixed value. Wrap fixed values in single quotes, like 'v2'.
• Passthrough behavior: what happens to a body whose content type has no template. When no template matches, pass the body through (the default); only when no templates exist; or never, which rejects the request with 415.
• Content handling: pass the body through unchanged (the default), convert binary to base64 text, or convert base64 text to binary.
• Mapping templates: in New template content type, type a content type, choose Add template, then write a Velocity-compatible template that builds the backend body. The trash icon removes a template.

Choose Save Integration Request to keep your changes. Integration settings are shared by every method that uses the same integration.

A method's Integration responses card turns what the backend returns into the method's response. Each integration response has a status code and a Selection pattern: a regular expression matched against the backend's status code, or against a function's error message. The one with an empty pattern is the default.

1. Under New integration response, type a Status and, optionally, a Selection pattern such as 5\d\d.
2. Choose Add response.
3. Click the new response to edit its Response mapping (for example method.response.header.X-Reply from integration.response.header.*), its Content handling and its templates. application/json template adds a template for JSON.
4. Choose Save for that status, such as Save 200 Response.

A header you map has to be declared on the method response first, under Method responses. Delete response removes the selected integration response after you confirm, and it can't be undone.

To test a REST method, open it under Methods in the API editor's Resources section and scroll to Test request. A test runs against the draft, so you can check a change before deploying it.

1. In Path with query string, type the path to call, such as /pets?limit=10.
2. Optional: fill in Headers (JSON), Body and Stage variables (JSON). Headers and stage variables must be JSON objects.
3. Choose Test Invoke.

Response shows the status code, how long the call took and the body. Execution log traces each step of the call, with tokens and secret values masked.

A test skips authorizers, API keys, throttling, quotas and caching. It doesn't touch any stage, and it isn't counted in metrics or usage. Owners, Admins and Managers can run tests; others see "Access unavailable".

To delete a method, choose Delete method in its ⋯ menu under Methods. Its request, response and integration settings go with it.

To delete a resource, select it in Resource tree and choose Delete branch. This removes the resource and every resource and method beneath it. The root resource, /, can't be deleted.

Pods asks you to confirm both, and neither can be undone. Deleting changes the draft only: stages keep serving their current deployment until you deploy again.

HTTP and WebSocket APIs are built from routes. Open the API from APIs, choose Routes in the API editor's section list, then New Route. Type a Route key and choose Create Route. Owners, Admins and Managers can add routes.

• HTTP APIs: a method and a path, such as GET /pets/{id} or ANY /{proxy+}, or $default for requests no other route matches. The method is GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS or ANY, and the path starts with /. A greedy {name+} part has to come last.
• WebSocket APIs: any key, such as $connect, $disconnect or a custom action like sendmessage, chosen from each message.

Route keys are up to 512 characters and unique within the API. In an HTTP API an exact method beats ANY, a greedy route needs the longest matching prefix, and a request that matches no route gets 404 Not Found.

The route list shows each route with its Integration (or Not connected) and its Authorization: None, IAM, JWT or Custom. It shows 25 routes a page; switch to 10, 50 or 100 at the bottom.

Each route's ⋯ menu in the API editor's Routes section has Authorization, which opens Route Authorization to set who can call the route. The Authorizers and resource policies guide covers the options.

Owners, Admins and Managers also see Delete. Pods asks you to confirm, then removes the route from the draft. It can't be undone, and live stages keep serving it until you deploy again.

The Route tester, under the route list of an HTTP API, shows which draft route a request would hit. Pick a Method and type a Path such as /pets/1, then choose Test Route.

The result names the matching route key and any path parameters it captured, such as {"id":"1"}. When nothing matches, it says why, and that requests there return 404 Not Found. The tester only reads the draft: it doesn't call your backend or change anything.