In our previous article, we discussed the major components of AWS Serverless architecture. We understood how the requests hit AWS API Gateway, get routed to AWS Lambda that process the request and stores data in database using services like AWS RDS or AWS DynamoDB and sends the response back to the user. In this article series, we discuss in-depth about AWS API Gateway, understand the various blocks associated with the request and utilise them in the tutorial. The article has been split into multiple pieces to allow you for taking a logical break if needed. This article in particular captures the initial concepts and the next one will capture the process of creating and testing APIs.
The pre-requisite for the tutorial is that you have an active AWS account. If you have got one, let’s jump right in and build some APIs. If not, please proceed towards registering a Free tier account. This will ensure that you are charged zero throughout the tutorial.
Introduction to API Gateway
This section gives a brief about API gateway for those who did not read through the previous article. You can skip this in case you are already aware about the API gateway service.
AWS API Gateway is an AWS service dedicated to creating, managing, processing and documenting REST web services. It provides an excellent console interface to route the user requests to server-less AWS Lambda functions or AWS SNS service to send notifications or even route to your own web server that lies behind the gateway. API Gateway essentially acts as a layer between your compute and user and provides the below features:
- Prevents high rate of requests and sudden spikes
- Authorises requests using AWS Lambda
- Processes request body and maps it to a desired format
- Validates request body and headers
- Handles errors and maps the right messages to response
Understanding types of APIs
In AWS API Gateway, a set of API routes are managed in a collection called the API suite. This helps us manage APIs for different web servers and applications separately. Navigate to AWS API gateway console to get started.
In the console, click on “Create New API”. In case you see a welcome screen (in case of a new account), please click Getting started to get going. You will be greeted with a screen that allows you to choose the type of API you wish to build. Here is a brief understanding of each type:
- HTTP API: This API type is presently in Beta mode and available specifically to support OAuth, OIDC auth support. The requests on an HTTP API can be routed to either AWS Lambda functions or to a web server only.
- WebSocket API: This is feature recently released by AWS for public use. The Websocket API allows the user application to create long-lived web socket connections with the API gateway. These connections allows faster communication and lower data exchange latency.
- REST API: This is the generic REST web service API type. This type of suite is normally able to route web requests of GET, POST, PUT, OPTIONS and DELETE type primarily. This type of API suite provides the full set of features listed above.
- REST API (private): This is a privately deployed instance of API suite. Unlike the public suites, the API in the private suite can be accessed only from within the respective AWS VPC or via VPC endpoints.
Creating first API suite
We will proceed with the REST API type of suite. Click Build to begin with the creation. You will see a list of selections to make. Let us understand each section below:
The protocol section allows you to choose how the user would connect to the API gateway. As I explained above, the protocol we will proceed with is REST for now. In case you wish to build a web socket based backend, you can choose WebSocket protocol.
The next section provides you options to get started. To create a new suite, you can choose either of the below:
- New API – Fresh empty
- Clone from existing API – Clone an existing API suite
- Import from Swagger or Open API3 – These are standard API documentation tools. API gateway allows you to use a swagger json or Open API 3 dump to create all the routes for your APIs automatically
- Example API – This option is for the beginners who wish to understand API gateway by creating an example suite.
Since we plan to cover the creation in depth, we will proceed with the creation of new empty API suite. Enter the name and description for the suite and click Create API to proceed. You would be welcomed with a side menu and actions menu as shown below. In the next section, we will discuss these menu items, terminologies and create our first resource.
Understanding API Gateway terminologies
The above images displays a lot of keywords that might not be clear to you at this point. In this section, I will try and explain you each keyword to allow you to proceed smoothly.
Resources in an API suite are the URL entities that you create. For instance, consider a web application that allows you to create a project and task. The URL for the project APIs and task APIs will be
/tasks respectively. Each of this can be called as a resource in AWS API gateway. Every resource in API gateway can have child resources. For instance, consider the URL to get list of project types –
/projects/types. Here, types is a child resource for the projects.
In the action menu, notice the keyword
method in the create actions. Every REST web service can have five main methods – GET, POST, PUT, DELETE and OPTIONS. These are the standard HTML request types and used to configure each resource with required APIs type. Each method is mapped either to a Lambda function call or a AWS service call.
Stages is a feature of API gateway that allows you to deploy various versions of API. For instance, a stage v1 can identify API changes for v1. A stage v2 can identify the APIs for v2. The URL for accessing APIs are suffixed by these stage names like
api.application.com/stage/resource-path. This ensures that a particular stage API can be accessed when desired.
API gateway takes away the pain of coding authorisation function for each APIs. It validates every API gateway resource call at gateway level via Authorizers. An authorizer can be a Lambda function that takes headers and desired body parameters as input and return a success or failure. This ensures that your compute resources are used only if an authorised user hits the API gateway. This helps in preventing unnecessary traffic on the compute resources.
This feature helps you to configure some static responses for error codes. These responses are sent back to the user when a respective error occurs in API gateway processing. For instance, a failure in Authoriser execution can result in a status 500, hitting the maximum api gateway limits can result in 429 – too many requests error and so on. These responses can be modified to get a better idea on whether the errors are taking place on API gateway or at compute level.
Model are business objects that are expected to be consumed by the API gateway resources. Models are defined in API gateway to validate the incoming request body against a JSON schema defined in this tab. AWS API Gateway follows the JSONSchema standard for API gateway model definition. This allow you to define basic validations like minimum, maximum, length and required or not. Thus, a lot of coding over-head of validating request body is also taken off from the compute resources.
Resource policy, as the name suggests, is the policy to control access to the APIs created on API gateway. Resource policy can help control access based on account ID, instance profile, AWS user or IP addresses too. Resource policy is the primary decision maker for authorising a request. It is written in the form of a JSON. AWS provides ready-to-use templates for whitelisting specific accounts or users or IP range.
Swagger has been a standard for REST API documentation for quite a while now. AWS API Gateway provides the facility to import Swagger documentation directly to API gateway and also allows you to customize the documentation right from the API gateway console. The Documentation link in the above image points to the same. You can add information about the API, import the same and publish for the users using the documentation facility.
API Gateway – Other Features
AWS API Gateway is a service with defined limits just like any other service on AWS. This means the amount of calls allowed for a particular API suite is limited. This makes it necessary to control the count of API requests made per second. This section discusses features that focus on these limits and logging of the API requests.
AWS API Gateway is primarily used by organizations to expose their backend to a third party while keeping the access controlled and secure. API keys is a feature that allows you to identify the client accessing the APIs. The image below describes how you can control the access to a resource by mandating the need for an API key. The detailed process of setting up an API key will be discussed in next article.
API gateway provides a facility to define a usage plan to enforce limits on the corresponding API suite. This allows to manage various subscriptions plans for softwares where you provide API as a service. The usage plans are a way of providing controlled access to every organization or individual accessing the APIs. This control is enforced by using API Keys discussed above. You can read more about setting up the usage here
Client Certificates and VPC links
Occasionally there is a requirement to use a specific domain and it is necessary to certificate based authorisation to allow only specific authorised domains to make an API call. To allow this, API Gateway provides you with the ability to create or add client side certificates that will be validated before allowing the request to go through. Moreover, they also provide the facility to create a VPC linking via Network Load balancer service to allow a private cloud or hybrid cloud format setup for the API access.
Conclusion so far
This article has elaborately discussed various terminologies and features of AWS API Gateway. It is a service that lies at the root level of the Serverless architectures on AWS. AWS API gateway provides everything from basic API proxying to throttling, access control, usage limits and excellent documentation facility to refer to later. Additionally, it also allows you to import APIs directly via Swagger – Something we will look into in the next article. Do subscribe to notifications for staying updated.
Feel free to comment in case of any doubts! – I’ll be there to answer.