Set up a method using the API Gateway console - Amazon API Gateway

Set up a method using the API Gateway 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.

Edit an API Gateway method request in the API Gateway 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.

  1. In the Resources pane, choose your method, and then choose the Method request tab.

  2. In the Method request settings section, choose Edit.

  3. 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.

    2. 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:

      { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "resource-statement" ] } ] }

      In this access policy, resource-statement 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 an API with IAM permissions.

      To create the IAM role, you can adapt the instructions in the following tutorial, Create a Lambda function for Lambda non-proxy integration.

    3. 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.

    4. 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 a REST API using Amazon Cognito user pools as authorizer.

  4. 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 Use request validation in API Gateway.

  5. Select API key required to require an API key. When enabled, API keys are used in usage plans to throttle client traffic.

  6. (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.

  7. To add a query string parameter to the method, do the following:

    1. Choose URL Query string parameters, and then choose Add query string.

    2. For Name, enter the name of the query string parameter.

    3. Select Required if the newly created query string parameter is to be used for request validation. For more information about the request validation, see Use request validation in API Gateway.

    4. 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.

    To remove the query string parameter, choose Remove.

  8. To add a header parameter to the method, do the following:

    1. Choose HTTP request headers, and then choose Add header.

    2. For Name, enter the name of the header.

    3. Select Required if the newly created header is to be used for request validation. For more information about the request validation, see Use request validation in API Gateway.

    4. 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.

    To remove the header, choose Remove.

  9. 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.

    2. For Content-type, enter a MIME-type (for example, application/json).

    3. 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 collection of the API. For more information about creating a model, see Understanding data models.

      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#, Objective-C, and Swift. It is only required if request validation is enabled against the payload.

  10. Choose Save.

Set up an API Gateway method response using the API Gateway 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.

  2. In the Method response settings section, choose Create response.

  3. 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.

  4. Choose Add header.

  5. For Header name, enter a name.

    To return a header from the backend to the client, add the header in the method response.

  6. 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.

  7. 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.