3 Steps to Create Your First API in AWS (using API Gateway, OpenAPI, and GitHub)

In a world obsessed with creating and consuming APIs, where committing files to GitHub is simply more important than life itself… by mixing OpenAPI and GitHub together and sprinkling a little AWS into the mix, you can have a powerful, easy, and scalable API.

Quick Links to Work the Steps
Warm-Up
Step 1: Add Data to a GitHub Repo
Step 2: Create the API Specification
Step 3: Set Up API Gateway

While these steps are quick and easy, the end result is a publicly-available API that you could use for your public-facing website.

Because of the low cost of API Gateway’s HTTP API (and that AWS Billing Notification you most definitely will have created), there is no big risk to sending your little baby API into the world.

Warm Up

Before these three steps, be sure have a GitHub account set up at https://github.com/.

GitHub is free to use, and by setting up your account, you will have access to a profile page that quickly shows you how little coding you’ve done in the past year.

Rookie numbers. The light grey means you’re not “crushing it” hard enough. Have you considered cutting all personal ties?

1 Step

Add Data to a GitHub Repo

Log in to your GitHub account and create a new git repository. This will be used to store the JSON data file our API will be sinking its teeth into.

Make sure the repository is set to Public, as the API Gateway will need read access to these files.

This repository will contain several JSON files that will make up the data our API will be accessing.

Create the JSON file data/pets.json in your git repository. This will be the data returned when the GET /pets API endpoint is called, our list of pets.

You can find an example file at https://github.com/three-steps/pets/blob/master/data/pets.json. We are using a list of five pets.

In addition to the list, we want to be able to provide more specific information about a specific pet. For that, we will need additional JSON files.

Take each pet item in the data/pets.json file and create individual files named with the id of the pet and commit them to the same directory as data/pets.json.

Real World Alert: Anyone who has gone through the trials and tribulations of SQL may be dismayed that we are duplicating so much data into different files. There must be a better way, right? Maybe a relational database with some hawt-and-tempting normalization? That depends on what you’re trying to do. For what we’re doing, this works well. We are replicating what you will find in many NoSQL databases, like Amazon’s DynamoDB. And by doing this on GitHub, we’re hosting our data for free.

In the end, you should have a data directory with files labelled from 1.json to 5.json, as well as your original pets.json file. An example of a full set of data can be found https://github.com/three-steps/pets.

That’s all we need for the data side of this API.

2 Step

Create the API Specification

For our next step, we will create an API spec file using the OpenAPI Specification (https://www.openapis.org). The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs. By using JSON or YAML, we can create a document that describes the API we would like to build.

With this API document you can do things like:

1. Generate Client APIs (in different languages)
2. Generate Static Documentation (html/markdown/etc.)
3. Create API Gateway Endpoints (we will do this in Step 3)

The OpenAPI spec we will be using can be found below or at https://github.com/three-steps/pets/blob/master/openapi.yaml

This OpenAPI specification file creates two paths: /pets and /pets/{petId}. Under each path there is a uri key. The uri specifies which data will be returned. For /pets it will return https://raw.githubusercontent.com/three-steps/pets/master/data/pets.json.

For /pets/{petId}, the different data needs to be provided for every petId.

Since we created individual JSON documents for every {petId}.json, we can use the {petId} variable in the /pets/{petId} uri to retrieve the data unique to each {petId}.

One thing you will notice in this OpenAPI specification file, is a special property called x-amazon-apigateway-integration. This is an OpenAPI extension, which allows a vendor — in this case, AWS — to add support for functionality that is specific to its products.

(You can find a list of API Gateway OpenAPI extensions here: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)

This x-amazon-apigateway-integration extension in our OpenAPI spec allows to attach an API endpoint to an AWS-supported backend. In this example, we are using AWS’ http_proxy backend integration to attach API Gateway to a GitHub URL.

3 Step

Set Up API Gateway

Finally, with the OpenAPI specification document completed, we can log into the AWS Management Console and visit the API Gateway service.

Select Create API.

API Gateway comes in multiple types. Each type has different OpenAPI extensions. The OpenAPI document created in Step 2 uses the latest extensions, which are only compatible with the HTTP API.

(HTTP API is the new hotness over REST API, and should be used unless you have specific needs that HTTP API does not yet have implemented. That’s not a problem for us.)

Select Import inside the HTTP API box, and then import the OpenAPI specification you created and click Create API.

Once the API is created, a Stage needs to be created. A Stage is a deployment and creates a URL for the API.

Select Stages from the left menu and then click Create.

This will take you to the Create Stage page:

You will need to provide a name for the stage. This name will be appended to the URL as a subdirectory. You can enter $default as the Stage Name and no subdirectory will be appended; this is probably better for what we’re trying to do.

It is recommended to Enable automatic deployment, so that any changes you make to the specification are automatically deployed.

With the name and the automatic deployments checked, click Create to complete the creation of the Stage.

Once the Stage has been created, an Invoke URL is generated and shown on the Details page for your OpenAPI Petstore API:

You can use this Invoke URL to build your actual endpoint URLs; for instance, appending /pets at the end of the Invoke URL creates your Pets Listing endpoint. You can paste that endpoint URL into your browser to see our listing of pets:

And for the individual Pet endpoints, you can use the pet id (any number from 1–5) to return the Pet details, e.g., https://XXXXXXXXX.executre-api.us-east-1.amazonaws.com/pets/1

Now you have an API that can be used by your website or application. You can create a ReactJS or Angular client-side app, or connect to this API using a server or container.

Real World Alert, Part 2: if you want to put private data into an API, you wouldn’t want to use a public GitHub repo to store it, and you wouldn’t want to run API Gateway without requiring authentication on the endpoints.

So now we’ve worked the steps

As mentioned at the start of our journey, the end result can be used as-is, if your data isn’t considered private.

You can update your data repo at any point to update your data, and you can even add additional endpoints by adding new files to GitHub, updating the OpenAPI Specification YAML file, and using the Reimport option to update your API Gateway to use a new version of the YAML.

And that’s all it takes to spin up an API. Hooray!