# Methods for REST APIs in API Gateway Methods In API Gateway, an API method embodies a [method request](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) and a [method response](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). You set up an API method to define what a client should or must do to submit a request to access the service at the backend and to define the responses that the client receives in return. For input, you can choose method request parameters, or an applicable payload, for the client to provide the required or optional data at run time. For output, you determine the method response status code, headers, and applicable body as targets to map the backend response data into, before they are returned to the client. To help the client developer understand the behaviors and the input and output formats of your API, you can [document your API](api-gateway-documenting-api.md) and [provide proper error messages](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) for [invalid requests](api-gateway-method-request-validation.md). An API method request is an HTTP request. To set up the method request, you configure an HTTP method (or verb), the path to an API [resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), headers, applicable query string parameters. You also configure a payload when the HTTP method is `POST`, `PUT`, or `PATCH`. For example, to retrieve a pet using the [PetStore sample API](api-gateway-create-api-from-example.md), you define the API method request of `GET /pets/{petId}`, where `{petId}` is a path parameter that can take a number at run time. ``` GET /pets/1 Host: apigateway.us-east-1.amazonaws.com ... ``` If the client specifies an incorrect path, for example, `/pet/1` or `/pets/one` instead of `/pets/1`, an exception is thrown. An API method response is an HTTP response with a given status code. For a non-proxy integration, you must set up method responses to specify the required or optional targets of mappings. These transform integration response headers or body to associated method response headers or body. The mapping can be as simple as an [identity transform](https://en.wikipedia.org/wiki/Identity_transform) that passes the headers or body through the integration as-is. For example, the following `200` method response shows an example of passthrough of a successful integration response as-is. ``` 200 OK Content-Type: application/json ... { "id": "1", "type": "dog", "price": "$249.99" } ``` In principle, you can define a method response corresponding to a specific response from the backend. Typically, this involves any 2XX, 4XX, and 5XX responses. However, this may not be practical, because often you may not know in advance all the responses that a backend may return. In practice, you can designate one method response as the default to handle the unknown or unmapped responses from the backend. It is good practice to designate the 500 response as the default. In any case, you must set up at least one method response for non-proxy integrations. Otherwise, API Gateway returns a 500 error response to the client even when the request succeeds at the backend. To support a strongly typed SDK, such as a Java SDK, for your API, you should define the data model for input for the method request, and define the data model for output of the method response. ## Prerequisites Before setting up an API method, verify the following: + You must have the method available in API Gateway. Follow the instructions in [Tutorial: Create a REST API with an HTTP non-proxy integration](api-gateway-create-api-step-by-step.md). + If you want the method to communicate with a Lambda function, you must have already created the Lambda invocation role and Lambda execution role in IAM. You must also have created the Lambda function with which your method will communicate in AWS Lambda. To create the roles and function, use the instructions in [Create a Lambda function for Lambda non-proxy integration](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda) of the [Choose an AWS Lambda integration tutorial](getting-started-with-lambda-integration.md). + If you want the method to communicate with an HTTP or HTTP proxy integration, you must have already created, and have access to, the HTTP endpoint URL with which your method will communicate. + Verify that your certificates for HTTP and HTTP proxy endpoints are supported by API Gateway. For details see [API Gateway-supported certificate authorities for HTTP and HTTP proxy integrations in API Gateway](api-gateway-supported-certificate-authorities-for-http-endpoints.md). **Topics** + [ ## Prerequisites ](#method-setting-prerequisites) + [ # Set up a method request in API Gateway ](api-gateway-method-settings-method-request.md) + [ # Set up a method response in API Gateway ](api-gateway-method-settings-method-response.md) + [ # Set up a method using the API Gateway console ](how-to-set-up-method-using-console.md) # Set up a method request in API Gateway Set up method request Setting up a method request involves performing the following tasks, after creating a [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) resource: 1. Creating a new API or choosing an existing API [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) entity. 1. Creating an API [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) resource that is a specific HTTP verb on the new or chosen API `Resource`. This task can be further divided into the following sub tasks: + Adding an HTTP method to the method request + Configuring request parameters + Defining a model for the request body + Enacting an authorization scheme + Enabling request validation You can perform these tasks using the following methods: + [API Gateway console](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console) + AWS CLI commands ([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) and [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html)) + AWS SDK functions (for example, in Node.js, [createResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) and [putMethod](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property)) + API Gateway REST API ([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) and [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)). **Topics** + [ ## Set up API resources ](#setup-method-resources) + [ ## Set up an HTTP method ](#setup-method-add-http-method) + [ ## Set up method request parameters ](#setup-method-request-parameters) + [ ## Set up a method request model ](#setup-method-request-model) + [ ## Set up method request authorization ](#setup-method-request-authorization) + [ ## Set up method request validation ](#setup-method-request-validation) ## Set up API resources In an API Gateway API, you expose addressable resources as a tree of API [Resources](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) entities, with the root resource (`/`) at the top of the hierarchy. The root resource is relative to the API's base URL, which consists of the API endpoint and a stage name. In the API Gateway console, this base URI is referred to as the **Invoke URI** and is displayed in the API's stage editor after the API is deployed. The API endpoint can be a default host name or a custom domain name. The default host name is of the following format: ``` {api-id}.execute-api.{region}.amazonaws.com ``` In this format, the *\$1api-id\$1* represents the API identifier that is generated by API Gateway. The `{region}` variable represents the AWS Region (for example, `us-east-1`) that you chose when creating the API. A custom domain name is any user-friendly name under a valid internet domain. For example, if you have registered an internet domain of `example.com`, any of `*.example.com` is a valid custom domain name. For more information, see [create a custom domain name](how-to-custom-domains.md). For the [PetStore sample API](api-gateway-create-api-from-example.md), the root resource (`/`) exposes the pet store. The `/pets` resource represents the collection of pets available in the pet store. The `/pets/{petId}` exposes an individual pet of a given identifier (`petId`). The path parameter of `{petId}` is part of the request parameters. To set up an API resource, you choose an existing resource as its parent and then create the child resource under this parent resource. You start with the root resource as a parent, add a resource to this parent, add another resource to this child resource as the new parent, and so on, to its parent identifier. Then you add the named resource to the parent. The following [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) command retrieves all the resources of an API: ``` aws apigateway get-resources --rest-api-id apiId ``` For the PetStore sample API, the output looks like the following: ``` { "items": [ { "path": "/pets", "resourceMethods": { "GET": {} }, "id": "6sxz2j", "pathPart": "pets", "parentId": "svzr2028x8" }, { "path": "/pets/{petId}", "resourceMethods": { "GET": {} }, "id": "rjkmth", "pathPart": "{petId}", "parentId": "6sxz2j" }, { "path": "/", "id": "svzr2028x8" } ] } ``` Each item lists the identifiers of the resource (`id`) and, except for the root resource, its immediate parent (`parentId`), as well as the resource name (`pathPart`). The root resource is special in that it does not have any parent. After choosing a resource as the parent, use the following command to add a child resource: ``` aws apigateway create-resource --rest-api-id apiId \ --parent-id parentId \ --path-part resourceName ``` For example, to add pet food for sale on the PetStore website, use the following command: ``` aws apigateway create-resource --rest-api-id a1b2c3 \ --parent-id svzr2028x8 \ --path-part food ``` The output will look like the following: ``` { "path": "/food", "pathPart": "food", "id": "xdsvhp", "parentId": "svzr2028x8" } ``` ### Use a proxy resource to streamline API setup As business grows, the PetStore owner may decide to add food, toys, and other pet-related items for sale. To support this, you can add `/food`, `/toys`, and other resources under the root resource. Under each sale category, you may also want to add more resources, such as `/food/{type}/{item}`, `/toys/{type}/{item}`, etc. This can get tedious. If you decide to add a middle layer `{subtype}` to the resource paths to change the path hierarchy into `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}`, etc., the changes will break the existing API set up. To avoid this, you can use an API Gateway [proxy resource](api-gateway-set-up-simple-proxy.md) to expose a set of API resources all at once. API Gateway defines a proxy resource as a placeholder for a resource to be specified when the request is submitted. A proxy resource is expressed by a special path parameter of `{proxy+}`, often referred to as a greedy path parameter. The `+` sign indicates whichever child resources are appended to it. The `/parent/{proxy+}` placeholder stands for any resource matching the path pattern of `/parent/*`. You can use any string for the greedy path parameter name. The following [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) command creates a proxy resource under the root (`/{proxy+}`): ``` aws apigateway create-resource --rest-api-id apiId \ --parent-id rootResourceId \ --path-part {proxy+} ``` The output will look like the following: ``` { "path": "/{proxy+}", "pathPart": "{proxy+}", "id": "234jdr", "parentId": "svzr2028x8" } ``` For the `PetStore` API example, you can use `/{proxy+}` to represent both the `/pets` and `/pets/{petId}`. This proxy resource can also reference any other (existing or to-be-added) resources, such as `/food/{type}/{item}`, `/toys/{type}/{item}`, etc., or `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}`, etc. The backend developer determines the resource hierarchy and the client developer is responsible for understanding it. API Gateway simply passes whatever the client submitted to the backend. An API can have more than one proxy resource. For example, the following proxy resources are allowed within an API, assuming `/parent/{proxy+}` is not the same parent as `/parent/{child}/{proxy+}`. ``` /{proxy+} /parent/{proxy+} /parent/{child}/{proxy+} ``` When a proxy resource has non-proxy siblings, the sibling resources are excluded from the representation of the proxy resource. For the preceding examples, `/{proxy+}` refers to any resources under the root resource except for the `/parent[/*]` resources. In other words, a method request against a specific resource takes precedence over a method request against a generic resource at the same level of the resource hierarchy. The following table shows how API Gateway routes requests to the following resources for the `prod` stage of an API. ``` ANY /{proxy+} GET /pets/{proxy+} GET /pets/dog ``` | Request | Selected route | Explanation | | --- | --- | --- | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | The request fully matches this resource. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | The `/pets/{proxy+}` greedy path variable catches this request. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | The `/{proxy+}` greedy path variable catches this request. | A proxy resource cannot have any child resource. Any API resource after `{proxy+}` is redundant and ambiguous. The following proxy resources are not allowed within an API. ``` /{proxy+}/child /parent/{proxy+}/{child} /parent/{child}/{proxy+}/{grandchild+} ``` ## Set up an HTTP method An API method request is encapsulated by the API Gateway [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) resource. To set up the method request, you must first instantiate the `Method` resource, setting at least an HTTP method and an authorization type on the method. Closely associated with the proxy resource, API Gateway supports an HTTP method of `ANY`. This `ANY` method represents any HTTP method that is to be supplied at run time. It allows you to use a single API method setup for all of the supported HTTP methods of `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST`, and `PUT`. You can set up the `ANY` method on a non-proxy resource as well. Combining the `ANY` method with a proxy resource, you get a single API method setup for all of the supported HTTP methods against any resources of an API. Furthermore, the backend can evolve without breaking the existing API setup. Before setting up an API method, consider who can call the method. Set the authorization type according to your plan. For open access, set it to `NONE`. To use IAM permissions, set the authorization type to `AWS_IAM`. To use a Lambda authorizer function, set this property to `CUSTOM`. To use an Amazon Cognito user pool, set the authorization type to `COGNITO_USER_POOLS`. The following [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) command creates a method request for the `ANY` verb using IAM permissions to control its access. ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method ANY \ --authorization-type AWS_IAM ``` To create an API method request with a different authorization type, see [Set up method request authorization](#setup-method-request-authorization). ## Set up method request parameters Method request parameters are a way for a client to provide input data or execution context necessary to complete the method request. A method parameter can be a path parameter, a header, or a query string parameter. As part of method request setup, you must declare required request parameters to make them available for the client. For non-proxy integration, you can translate these request parameters to a form that is compatible with the backend requirement. For example, for the `GET /pets/{petId}` method request, the `{petId}` path variable is a required request parameter. You can declare this path parameter when calling the `put-method` command of the AWS CLI. The following [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) command creates a method with a required path parameter: ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id rjkmth \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.path.petId=true ``` If a parameter is not required, you can set it to `false` in `request-parameters`. For example, if the `GET /pets` method uses an optional query string parameter of `type`, and an optional header parameter of `age`, you can declare them using the following [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) command: ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.querystring.type=false,method.request.header.age=false ``` Instead of this abbreviated form, you can use a JSON string to set the `request-parameters` value: ``` '{"method.request.querystring.type":false,"method.request.header.age":false}' ``` With this setup, the client can query pets by type: ``` GET /pets?type=dog ``` And the client can query dogs who are puppies as follows: ``` GET /pets?type=dog age:puppy ``` For information on how to map method request parameters to integration request parameters, see [Integrations for REST APIs in API Gateway](how-to-integration-settings.md). ## Set up a method request model For an API method that can take input data in a payload, you can use a model. A model is expressed in a [JSON schema draft 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) and describes the data structure of the request body. With a model, a client can determine how to construct a method request payload as input. More importantly, API Gateway uses the model to [validate a request](api-gateway-method-request-validation.md), [generate an SDK](how-to-generate-sdk.md), and initialize a mapping template for setting up the integration in the API Gateway console. For information about how to create a [model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html), see [Understanding data models](models-mappings-models.md). Depending on the content types, a method payload can have different formats. A model is indexed against the media type of the applied payload. API Gateway uses the `Content-Type` request header to determine the content type. To set up method request models, add key-value pairs of the `"media-type":"model-name"` format to the `requestModels` map when calling the AWS CLI `put-method` command. To use the same model regardless of the content type, specify `$default` as the key. For example, to set a model on the JSON payload of the `POST /pets` method request of the PetStore example API, you can use the following [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) command: ``` aws apigateway put-method \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method POST \ --authorization-type "NONE" \ --request-models '{"application/json":"petModel"}' ``` Here, `petModel` is the `name` property value of a [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) resource describing a pet. The actual schema definition is expressed as a JSON string value of the [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema) property of the `Model` resource. In a Java, or other strongly typed SDK, of the API, the input data is cast as the `petModel` class derived from the schema definition. With the request model, the input data in the generated SDK is cast into the `Empty` class, which is derived from the default `Empty` model. In this case, the client cannot instantiate the correct data class to provide the required input. ## Set up method request authorization To control who can call the API method, you can configure the [authorization type](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType) on the method. You can use this type to enact one of the supported authorizers, including IAM roles and policies (`AWS_IAM`), an Amazon Cognito user pool (`COGNITO_USER_POOLS`), or a Lambda authorizer (`CUSTOM`). To use IAM permissions to authorize access to the API method, set the `authorization-type` input property to **AWS\$1IAM**. When you set this option, API Gateway verifies the caller's signature on the request based on the caller's credentials. If the verified user has permission to call the method, it accepts the request. Otherwise, it rejects the request and the caller receives an unauthorized error response. The call to the method doesn't succeed unless the caller has permission to invoke the API method. The following IAM policy grants permission to the caller to call any API methods created within the same AWS account: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": "arn:aws:execute-api:*:*:*" } ] } ``` ------ For more information, see [Control access to a REST API with IAM permissions](permissions.md). Currently, you can only grant this policy to the users, groups, and roles within the API owner's AWS account. Users from a different AWS account can call the API methods only if allowed to assume a role within the API owner's AWS account with the necessary permissions to call the `execute-api:Invoke` action. For information on cross-account permissions, see [Using IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). You can use AWS CLI, an AWS SDK, or a REST API client, such as [Postman](https://www.postman.com/), which implements [Signature Version 4 (SigV4) signing](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). To use a Lambda authorizer to authorize access to the API method, set the `authorization-type` input property to `CUSTOM` and set the [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) input property to the [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) property value of a Lambda authorizer that already exists. The referenced Lambda authorizer can be of the `TOKEN` or `REQUEST` type. For information about creating a Lambda authorizer, see [Use API Gateway Lambda authorizers](apigateway-use-lambda-authorizer.md). To use an Amazon Cognito user pool to authorize access to the API method, set the `authorization-type` input property to `COGNITO_USER_POOLS` and set the [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) input property to the [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) property value of the `COGNITO_USER_POOLS` authorizer that was already created. For information about creating an Amazon Cognito user pool authorizer, see [Control access to REST APIs using Amazon Cognito user pools as an authorizer](apigateway-integrate-with-cognito.md). ## Set up method request validation You can enable request validation when setting up an API method request. You need to first create a [request validator](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html). The following [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html) command creates a body-only request validator. ``` aws apigateway create-request-validator \ --rest-api-id 7zw9uyk9kl \ --name bodyOnlyValidator \ --validate-request-body \ --no-validate-request-parameters ``` The output will look like the following: ``` { "validateRequestParameters": false, "validateRequestBody": true, "id": "jgpyy6", "name": "bodyOnlyValidator" } ``` You can use this request validator, to use request validation as part of the method request setup. The following [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) command creates a method request that requires the incoming request body to match the `PetModel` and has two request parameter that aren't required: ``` aws apigateway put-method \ --rest-api-id 7zw9uyk9kl \ --resource-id xdsvhp \ --http-method PUT \ --authorization-type "NONE" \ --request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \ --request-models '{"application/json":"petModel"}' \ --request-validator-id jgpyy6 ``` To include a request parameter in the request validation, you must set `validateRequestParameters` to `true` for the request validator, and set the specific request parameter to `true` in the `put-method` command. # Set up a method response in API Gateway Set up method response An API method response encapsulates the output of an API method request that the client will receive. The output data includes an HTTP status code, some headers, and possibly a body. With non-proxy integrations, the specified response parameters and body can be mapped from the associated integration response data or can be assigned certain static values according to mappings. These mappings are specified in the integration response. The mapping can be an identical transformation that passes the integration response through as-is. With a proxy integration, API Gateway passes the backend response through to the method response automatically. There is no need for you to set up the API method response. However, with the Lambda proxy integration, the Lambda function must return a result of [this output format](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) for API Gateway to successfully map the integration response to a method response. Programmatically, the method response setup amounts to creating a [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) resource of API Gateway and setting the properties of [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters), and [responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels). When setting status codes for an API method, you should choose one as the default to handle any integration response of an unanticipated status code. It is reasonable to set `500` as the default because this amounts to casting otherwise unmapped responses as a server-side error. For instructional reasons, the API Gateway console sets the `200` response as the default. But you can reset it to the `500` response. To set up a method response, you must have created the method request. ## Set up method response status code The status code of a method response defines a type of response. For example, responses of 200, 400, and 500 indicate successful, client-side error and server-side error responses, respectively. To set up a method response status code, set the [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode) property to an HTTP status code. The following [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) command creates `200` method response. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 ``` ## Set up method response parameters Method response parameters define which headers the client receives in response to the associated method request. Response parameters also specify a target to which API Gateway maps an integration response parameter, according to mappings prescribed in the API method's integration response. To set up the method response parameters, add to the [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) map of `MethodResponse` key-value pairs of the `"{parameter-name}":"{boolean}"` format. The following [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) command sets the `my-header` header. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false ``` ## Set up method response models A method response model defines a format of the method response body. Setting up a method response model is necessary when you generate a strongly typed SDK for the API. It ensures that the output is cast into an appropriate class in Java or Objective-C. In other cases, setting a model is optional. Before setting up the response model, you must first create the model in API Gateway. To do so, you can call the `[create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html)` command. The following [create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html) command creates `PetStorePet` model to describe the body of the response to the `GET /pets/{petId}` method request. ``` aws apigateway create-model \ --rest-api-id vaz7da96z6 \ --content-type application/json \ --name PetStorePet \ --schema '{ \ "$schema": "http://json-schema.org/draft-04/schema#", \ "title": "PetStorePet", \ "type": "object", \ "properties": { \ "id": { "type": "number" }, \ "type": { "type": "string" }, \ "price": { "type": "number" } \ } \ }' ``` The result is created as an API Gateway [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) resource. To set up the method response models to define the payload format, add the "application/json":"PetStorePet" key-value pair to the [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels) map of [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) resource. The following [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) command creates a method response that uses a response model to define the payload format: ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false \ --response-models '{"application/json":"PetStorePet"}' ``` # Set up a method using the API Gateway console Set up method using the console When you create a method using the REST API console, you configure both the integration request and the method request. By default, API Gateway creates the `200` method response for your method. The following instructions show how to edit the method request settings and how to create additional method responses for your method. **Topics** + [ ## Edit an API Gateway method request in the API Gateway console ](#how-to-method-settings-callers-console) + [ ## Set up an API Gateway method response using the API Gateway console ](#how-to-method-response-settings-console) ## Edit an API Gateway method request in the API Gateway console Edit a method request in the console These instructions assume you have already created your method request. For more information on how to create a method, see [Set up an API integration request using the API Gateway console](how-to-method-settings-console.md). 1. In the **Resources** pane, choose your method, and then choose the **Method request** tab. 1. In the **Method request settings** section, choose **Edit**. 1. For **Authorization**, select an available authorizer. 1. To enable open access to the method for any user, select **None**. This step can be skipped if the default setting has not been changed. 1. To use IAM permissions to control the client access to the method, select `AWS_IAM`. With this choice, only users of the IAM roles with the correct IAM policy attached are allowed to call this method. To create the IAM role, specify an access policy with a format like the following: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/" ] } ] } ``` ------ In this access policy, `arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/` is the ARN of your method. You can find the ARN of your method by selecting the method on the **Resources** page. For more information about setting the IAM permissions, see [Control access to a REST API with IAM permissions](permissions.md). To create the IAM role, you can adapt the instructions in the following tutorial, [Create a Lambda function for Lambda non-proxy integration](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda). 1. To use a Lambda authorizer, select a token or a request authorizer. Create the Lambda authorizer to have this choice displayed in the dropdown menu. For information on how to create a Lambda authorizer, see [Use API Gateway Lambda authorizers](apigateway-use-lambda-authorizer.md). 1. To use an Amazon Cognito user pool, choose an available user pool under **Cognito user pool authorizers**. Create a user pool in Amazon Cognito and an Amazon Cognito user pool authorizer in API Gateway to have this choice displayed in the dropdown menu. For information on how to create an Amazon Cognito user pool authorizer, see [Control access to REST APIs using Amazon Cognito user pools as an authorizer](apigateway-integrate-with-cognito.md). 1. To specify request validation, select a value from the **Request Validator** dropdown menu. To turn off request validation, select **None**. For more information about each option, see [Request validation for REST APIs in API Gateway](api-gateway-method-request-validation.md). 1. Select **API key required** to require an API key. When enabled, API keys are used in [usage plans](api-gateway-api-usage-plans.md) to throttle client traffic. 1. (Optional) To assign an operation name in a Java SDK of this API, generated by API Gateway, for **Operation name**, enter a name. For example, for the method request of `GET /pets/{petId}`, the corresponding Java SDK operation name is, by default ,`GetPetsPetId`. This name is constructed from the method's HTTP verb (`GET`) and the resource path variable names (`Pets` and `PetId`). If you set the operation name as `getPetById`, the SDK operation name becomes `GetPetById`. 1. To add a query string parameter to the method, do the following: 1. Choose **URL Query string parameters**, and then choose **Add query string**. 1. For **Name**, enter the name of the query string parameter. 1. Select **Required** if the newly created query string parameter is to be used for request validation. For more information about the request validation, see [Request validation for REST APIs in API Gateway](api-gateway-method-request-validation.md). 1. Select **Caching** if the newly created query string parameter is to be used as part of a caching key. For more information about caching, see [Use method or integration parameters as cache keys to index cached responses](api-gateway-caching.md#enable-api-gateway-cache-keys). To remove the query string parameter, choose **Remove**. 1. To add a header parameter to the method, do the following: 1. Choose **HTTP request headers**, and then choose **Add header**. 1. For **Name**, enter the name of the header. 1. Select **Required** if the newly created header is to be used for request validation. For more information about the request validation, see [Request validation for REST APIs in API Gateway](api-gateway-method-request-validation.md). 1. Select **Caching** if the newly created header is to be used as part of a caching key. For more information about caching, see [Use method or integration parameters as cache keys to index cached responses](api-gateway-caching.md#enable-api-gateway-cache-keys). To remove the header, choose **Remove**. 1. To declare the payload format of a method request with the `POST`, `PUT`, or `PATCH` HTTP verb, choose **Request body**, and do the following: 1. Choose **Add model**. 1. For **Content-type**, enter a MIME-type (for example, `application/json`). 1. For **Model**, select a model from the dropdown menu. The currently available models for the API include the default `Empty` and `Error` models as well as any models you have created and added to the [Models](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) collection of the API. For more information about creating a model, see [Data models for REST APIs](models-mappings-models.md). **Note** The model is useful to inform the client of the expected data format of a payload. It is helpful to generate a skeletal mapping template. It is important to generate a strongly typed SDK of the API in such languages as Java, C\$1, Objective-C, and Swift. It is only required if request validation is enabled against the payload. 1. Choose **Save**. ## Set up an API Gateway method response using the API Gateway console Set up a method response using the console An API method can have one or more responses. Each response is indexed by its HTTP status code. By default, the API Gateway console adds `200` response to the method responses. You can modify it, for example, to have the method return `201` instead. You can add other responses, for example, `409` for access denial and `500` for uninitialized stage variables used. To use the API Gateway console to modify, delete, or add a response to an API method, follow these instructions. 1. In the **Resources** pane, choose your method, and then choose the **Method response** tab. You might need to choose the right arrow button to show the tab. 1. In the **Method response settings** section, choose **Create response**. 1. For **HTTP status code**, enter an HTTP status code such as `200`, `400`, or `500`. When a backend-returned response does not have a corresponding method response defined, API Gateway fails to return the response to the client. Instead, it returns a `500 Internal server error` error response. 1. Choose **Add header**. 1. For **Header name**, enter a name. To return a header from the backend to the client, add the header in the method response. 1. Choose **Add model** to define a format of the method response body. Enter the media type of the response payload for **Content type** and choose a model from the **Models** dropdown menu. 1. Choose **Save**. To modify an existing response, navigate to your method response, and then choose **Edit**. To change the **HTTP status code**, choose **Delete** and create a new method response. For every response returned from the backend, you must have a compatible response configured as the method response. However, the configuring method response headers and payload model are optional unless you map the result from the backend to the method response before returning to the client. Also, a method response payload model is important if you are generating a strongly typed SDK for your API.