Invoking a REST API in Amazon API Gateway - Amazon API Gateway

Invoking a REST API in Amazon API Gateway

To call a deployed API, clients submit requests to the URL for the API Gateway component service for API execution, known as execute-api.

The base URL for REST APIs is in the following format:

https://restapi_id.execute-api.region.amazonaws.com/stage_name/

where restapi_id is the API identifier, region is the AWS Region, and stage_name is the stage name of the API deployment.

Important

Before you can invoke an API, you must deploy it in API Gateway. For instructions on deploying an API, see Deploying a REST API in Amazon API Gateway.

Obtaining an API's invoke URL

You can use the console, the AWS CLI, or an exported OpenAPI definition to obtain an API's invoke URL.

Obtaining an API's invoke URL using the console

The following procedure shows how to obtain an API's invoke URL in the REST API console.

To obtain an API's invoke URL using the REST API console
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Choose a deployed API.

  3. From the main navigation pane, choose Stage.

  4. Under Stage details, choose the copy icon to copy your API's invoke URL.

    This URL is for the root resource of your API.

    
                After you create your REST API, the console shows your API's invoke URL.
  5. To obtain an API's invoke URL for another resource in your API, expand the stage under the secondary navigation pane, and then choose a method.

  6. Choose the copy icon to copy your API's resource-level invoke URL.

    
              After you expand the stage under the secondary navigation pane, the console shows your resource-level API's invoke URL.

Obtaining an API's invoke URL using the AWS CLI

The following procedure shows how to obtain an API's invoke URL using the AWS CLI.

To obtain an API's invoke URL using the AWS CLI
  1. Use the following command to obtain the rest-api-id. This command returns all rest-api-id values in your Region. For more information, see get-rest-apis.

    aws apigateway get-rest-apis
  2. Replace the example rest-api-id with your rest-api-id, replace the example {stage-name} with your {stage-name}, and replace the {region}, with your Region.

    https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/
Obtaining an API's invoke URL using the exported OpenAPI definition file of the API

You can also construct the root URL by combining the host and basePath fields of an exported OpenAPI definition file of the API. For instructions on how to export your API, see Export a REST API from API Gateway.

Invoking an API

You can call your deployed API using the browser, curl, or other applications, like Postman.

Additionally, you can use the API Gateway console to test an API call. Test uses the API Gateway's TestInvoke feature, which allows API testing before the API is deployed. For more information, see Use the API Gateway console to test a REST API method.

Note

Query string parameter values in an invocation URL cannot contain %%.

Invoking an API using a web browser

If your API permits anonymous access, you can use any web browser to invoke any GET method. Enter the complete invocation URL in the browser's address bar.

For other methods or any authentication-required calls, you must specify a payload or sign the requests. You can handle these in a script behind an HTML page or in a client application using one of the AWS SDKs.

Invoking an API using curl

You can use a tool like curl in your terminal to call your API. The following example curl command invokes the GET method on the getUsers resource of the prod stage of an API.

Linux or Macintosh
curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
Windows
curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers"