AWS API Gateway Tutorial, Part 2: Import and Deploy the API Gateway API

This portion of the tutorial has been adapted from the official AWS example. Please refer to this example for in-depth notes and discussion.

In this part of the AWS API Gateway tutorial, we will show you how to import and manage an API using API Gateway. More specifically, we will:

  • Import an API into API Gateway
  • Test an API import
  • Deploy an API for use with any front-end clients
  • Test an API deployment

In later parts of this tutorial, we will show how to secure the endpoints of this API using custom authorizers that accept Auth0 access tokens, as well as how we can integrate this API with our front-end JavaScript client.

Import and Configure the Pets API

Log in to your AWS account, and using the Services drop down located in the top navigation bar, go to the API Gateway Console.

If you've previously created an API, simply navigate to the API Gateway Console and click Create API. You'll be given the option to create the Example API on the Create new API form.

If you've never created an API using API Gateway, you'll see the following screen. Click Get Started to proceed.

You'll see a pop-up message welcoming you to API Gateway. Click OK to proceed.

On the Create new API form, you'll see that Example API is selected by default, and there's an example API defined in the editor. We'll use this API for the rest of our tutorial, so begin the API creation process by clicking Import.

When done, AWS will display a message indicating that your API created and populated with the provided data.

Notice that the API already has methods associated with it (namely, GET and POST). You can view the details of a method, modify its setup, or test the method invocation by clicking the method name from the resource tree.

Test Your API

Now that you've successfully imported your API, let's run some tests to ensure that everything works as expected. This exercise will also demonstrate some of the features of the API itself.

As an example, click POST under /pets. This brings up the Method Execution window that provides an overview of the POST method's structure and behaviors:

  • Method Request and Method Response: the API's interface with the front-end
  • Integration Request and Integration Response: the API's interface with the back-end

We can use this area to test the API we've created.

Click Test (shown on the Client sliver located in the middle of the page).

You'll be redirected to the /pets - POST - Method Test page.

Scroll to the bottom of the page, and provide the following snippet as the Request Body:

{"type": "dog", "price": 249.99}

The request body indicates the attributes of the pet we want to add to the database, as well as the cost for the pet.

Click Test to proceed.

You'll see the results of the test at the right side of the page.

Deploy the API

The test we just completed was done using the API Gateway console. To use the API with a different client, you'll need to deploy the API to a stage. You can do this via the Actions menu, which offers the Deploy API option.

You'll be asked to provide the following values:

Parameter Value
Deployment stage Choose [New Stage]
Stage name Provide a name for your stage
Stage description Provide a description for your stage
Deployment description Provide a description for your API deployment

Once you've provided the appropriate values, click Deploy to proceed.

Test the Deployment

When the API has successfully deployed, you'll be redirected to the Test Stage Editor. You can, at this point, test the API to see if it deployed correctly.

At the top of the Test Stage Editor window is a blue banner with your Invoke URL. This is the URL used to invoke the GET endpoint of your API.

Click on the link to submit the GET / method request in a browser. This should result in the following success response:

Next, we'll make a call to GET under /pets/{petId}. In the Stages page, expand the tree under Test.

You'll see an Invoke URL displayed in the blue banner at the top of the window. The final portion, {petID}, stands for a path variable. Replace this variable with 1, and navigate to the new URL using your browser. You should receive an HTTP 200 request with the following JSON payload:

{
  "id": 1,
  "type": "dog",
  "price": 249.99
}

Summary

In Part 2 of the AWS API Gateway tutorial, we covered how to:

  • Import an API into API Gateway
  • Test an API import
  • Deploy an API for use with any front-end clients
  • Test an API deployment

Now that we have a fully functional API that's managed by API Gateway, we'll...