Models, CORS & gateway responses

A model is a JSON Schema (draft-04) that describes a request or response body. REST and WebSocket APIs have models. To create one, open the API from APIs, choose Models in the API editor's section list, then New Model.

1. Type a Name: letters and digits only, up to 128, and unique within the API.
2. Keep or change the Content type. It starts as application/json.
3. Write the Schema. Or paste an example payload under Generate from sample JSON and choose Generate Schema: Pods writes a schema with each property's type, and marks every property required.
4. Choose Create Model.

The schema has to be a valid JSON object. All of an API's model schemas together can be up to 400 KB. Owners, Admins and Managers can manage models.

A REST method uses models in its details under Resources: Request models and Response models map a content type to a model. Besides the API's own models, you can pick the built-in Empty and Error. Generated SDKs also describe payloads from the API's models.

The Models list in the API editor shows each model's name and description, its Type, its Content type and how many Properties it has. Click a model, or choose Edit in its ⋯ menu, to change its content type or schema, then choose Save Changes. The name can't change. Members see View schema instead.

To delete a model, choose Delete in its ⋯ menu and confirm. Methods that referenced it no longer use it, and it can't be undone.

CORS settings let web pages on other sites call an HTTP API from the browser. Open the API from APIs and choose CORS in the API editor's section list.

• Allowed origins: type an origin such as https://example.com and choose Add, or add * for any origin. With no origins, Pods sends no CORS headers.
• Allowed methods: select GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS or * (any).
• Allowed headers and Exposed headers: comma separated, such as content-type, authorization.
• Max age: how long browsers can cache a preflight, from 0 to 86400 seconds.
• Allow credentials: lets browsers send cookies and authorization headers. It can't be on while * is an allowed origin.

Choose Save Changes. Only Owners and Admins can save CORS settings. Pods answers preflight requests itself, without running authorizers.

REST APIs set CORS per resource. Open the API's Resources section, select the resource, and choose Enable CORS next to Methods.

• Allow origin: a quoted value, '*' to start with.
• Allow headers: starts as Content-Type,X-Amz-Date,Authorization,X-Api-Key.
• Methods: GET, POST and OPTIONS start selected.

Choose Create OPTIONS Mock. Pods adds an OPTIONS method to the resource that answers 200 with the Access-Control-Allow-* headers, without calling a backend. It also adds the Access-Control-Allow-Origin header to the 200 responses of the methods you selected. Owners, Admins and Managers can do this.

Gateway responses are the errors Pods returns itself, before or instead of calling your backend: a missing API key, a throttled caller, a timed-out integration. REST APIs can change them. Open the API from APIs and choose Gateway Responses in the API editor's section list.

Each response type is listed with its status code and whether it's Default or Customized. Click one, or choose Edit in its ⋯ menu:

• Status code: leave it empty to keep the default.
• Response headers: one per line, such as gatewayresponse.header.Access-Control-Allow-Origin='*'.
• Template content type and Body template: the body to send, which can use $context.error.* values such as $context.error.messageString.

Choose Save Changes. To undo a customization, choose Reset to default in its ⋯ menu and confirm. A type you leave alone falls back to your DEFAULT_4XX or DEFAULT_5XX customization, if you made one. Owners, Admins and Managers can edit gateway responses; others can view them.

The gateway response types and their default status codes:

• ACCESS_DENIED 403, EXPIRED_TOKEN 403, INVALID_API_KEY 403, INVALID_SIGNATURE 403, MISSING_AUTHENTICATION_TOKEN 403, WAF_FILTERED 403
• UNAUTHORIZED 401
• BAD_REQUEST_PARAMETERS 400, BAD_REQUEST_BODY 400
• RESOURCE_NOT_FOUND 404
• REQUEST_TOO_LARGE 413, UNSUPPORTED_MEDIA_TYPE 415
• QUOTA_EXCEEDED 429, THROTTLED 429
• API_CONFIGURATION_ERROR 500, AUTHORIZER_CONFIGURATION_ERROR 500, AUTHORIZER_FAILURE 500
• INTEGRATION_FAILURE 504, INTEGRATION_TIMEOUT 504
• DEFAULT_4XX and DEFAULT_5XX: no status of their own. They apply to any 4xx or 5xx type you haven't customized.