Menu
Amazon API Gateway
Developer Guide

Set up a Method Using the API Gateway Console

Before setting up an API method, verify the following:

Set up an API Gateway Method Request in the API Gateway Console

To use the API Gateway console to specify an API's method request/response, and to configure how the method will authorize requests, follow these instructions.

Note

These instructions assume you have already completed the steps in Set up an API Integration Request Using the API Gateway Console . They are best used to supplement the discussions given in .

  1. With the method selected in the Resources pane, choose Method Request from the Method Execution pane.

  2. Under Settings, choose the pencil icon to open the Authorization drop-down menu and choose one of the available authorizers.

    1. To enable open access to the method for any user, choose 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, choose 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:

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

      In this access policy, resource-statement is the value of the ARN field in the Authorization Settings section. For more information about setting the IAM permissions, see Control Access an API with IAM Permissions.

      To create the IAM role, you can adapt the instructions in "To create the Lambda invocation role and its policy" and "To create the Lambda execution role and its policy" in the Create Lambda Functions section of the .

      To save your choice, choose Update. Otherwise, choose Cancel.

    3. To use a custom authorizer, choose one under Token authorizer. You must have created a custom authorizer to have this choice displayed in the drop-down menu. For information on how to create a custom authorizer, see Use API Gateway Custom Authorizers.

    4. To use an Amazon Cognito user pool, choose an available user pool under Cognito user pool authorizers. You must have created a user pool in Amazon Cognito and an Amazon Cognito user pool authorizer in API Gateway to have this choice displayed in the drop-down menu. For information on how to create an Amazon Cognito user pool authorizer, see Use Amazon Cognito User Pools.

  3. To enable or disable request validation, choose the pencil icon from the Request Validator drop-down menu and choose one of the listed options. For more information about each option, see Enable Request Validation in API Gateway.

  4. To require an API key, choose the pencil icon to open the API Key Required drop-down menu and choose either true or false according to your API requirements. When enabled, API keys are used in usage plans to throttle client traffic.

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

    1. Choose the arrow next to URL Query String Parameters, and then choose Add query string.

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

    3. Choose the check-mark icon to save the new query string parameter name.

    4. If the newly created query string parameter is to be used for request validation, choose the Required option. For more information about the request validation, see Enable Request Validation in API Gateway.

    5. If the newly created query string parameter is to be used as part of a caching key, check the Caching option. This is applicable only when caching is enabled. For more information about caching, see Use Method/Integration Parameters as Cache Keys.

    Tip

    To remove the query string parameter, choose the x icon associated with it and then choose Remove this parameter and any dependent parameters to confirm the removal.

    To change the name of the query string parameter, remove it and then create a new one.

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

    1. Choose the arrow next to HTTP Request Headers, and then choose Add header.

    2. For Name, type the name of the header parameter and then choose the check-mark icon to save the settings.

    3. If the newly created header parameter is to be used for request validation, choose the Required option. For more information about request validation, see Enable Request Validation in API Gateway.

    4. If the newly created header parameter is to be used as part of a caching key, choose the Caching option. This is applicable only when caching is enabled. For more information about caching, see Use Method/Integration Parameters as Cache Keys.

    Tip

    To remove the header parameter, choose the x icon associated with it and then choose Remove this parameter and any dependent parameters to confirm the removal.

    To change the name of the header parameter, remove it and then create a new one.

  7. To declare the payload format of a method request with the POST, PUT, or PATCH HTTP verb, expand Request Body, and do the following:

    1. Choose Add model.

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

    3. Open the Model name drop-down menu to choose an available model for the payload and choose the check-mark icon to save the settings.

      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 Create a Model.

      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.

  8. To assign an operation name in a Java SDK of this API, generated by API Gateway, expand SDK Settings and type a name in Operation 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.

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. Choose Method Response from Method Execution for a given method of an API resource.

  2. To add a new response, choose Add Response.

    1. Type an HTTP status code; for example, 200, 400, or 500) for HTTP Status, and then choose the check-mark icon to save the choice.

      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.

    2. Expand the response of the given status code.

    3. Choose Add Header.

    4. Type a name for Name under Response Headers for {status}, and then choose the check-mark icon to save the choice.

      If you need to translate any backend-returned header to one defined in a method response, you must first add the method response header as described in this step .

    5. Choose Add Response Model under Response Body for {status}.

    6. Type the media type of the response payload for Content type and choose a model from the Models drop-down menu.

    7. Choose the check-mark icon to save the settings.

  3. To modify an existing response, expand the response and follow Step 2 above.

  4. To remove a response, choose the x icon for the response and confirm you want to delete the 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.