INTRODUCTION👋

API Gateway is a fully-managed service that acts as a front door to your application's ecosystem.

It's easy to perceive it just as an HTTP mediator between a client and an internal AWS service like Lambda, but there's more to explore as it offers a lot of valuable features.

FOUNDATIONS🏗️

API Gateway allows you to securely create APIs at any scale, not only to expose AWS resources but also anything that speaks HTTP.

Major benefits: the request & response flow allows you to do a lot without writing much or any code, e.g.

• use a mapping templates written in the Velocity Template Language (VTL) to transform inputs
• authenticate via API keys in the API User Authorizer

REQUEST FLOW🔄

The Request Flow is everything that happens before the integration is triggered, like authentication and authorization processing (see Authorizers) or request validation.

RESPONSE FLOW🔁

The Response Flow is everything that comes after the integration, like transformations so your clients get an expected output for the results of your integration.

GATEWAY TYPES✨

API Gateway comes in three different flavors, offering different features and pricing:

• REST - the default and most common type
• HTTP - reduced set of features in comparison to REST, but way cheaper and easier to set up
• WebSockets - for building real-time applications

USAGE PLANS📊

API keys can be used as a method for rate limiting and throttling the clients of your APIs by defining:

• a threshold for the requests per second
• burst sizes: a time-window that can exceed the threshold
• the maximum number of requests for a time-window

This adds a layer of protection against flooding and misuse.

ℹ️ Requests which are blocked due to rate-limiting are not billed - this is the same for requests that are rejected due to invalid authentication/authorization by your Authorizers.

PROXY RESOURCE📋

Bind different HTTP methods to your integration.

Example: /api/v1/customers/{id}

It will bind calls for example to

• /api/v1/customers/BBie6fef
• but not to
• /api/v1/customers/BBie6fef/orders

You can extend the proxy indicator with a + to capture all values that come after.

Example: /api/v1/items/{proxy+}

Will match for example:

• /api/v1/customers
• /api/v1/orders
• /api/v1/orders/5a3d99ff

...and everything else that's under /api/v1.

AUTHORIZERS🔐

Authorizers enable you to protect your downstream services and forward a security context that contains information about the authenticated identity.

There are different types of authorizers, including the default JWT, a Cognito User Pool or a custom Lambda function.

The default JWT for HTTP Gateway is great to integrate with any identity provider supporting OAuth2/OpenID.

ERROR HANDLING⚠️

Your request can get rejected by your API for a lot of different reasons. Among other things:

• missing or invalid authorization
• payload does not match your validation model
• invalid methods or routes

By default, API Gateway will return a HTTP 400 Bad Request response with a message indicating the type of failure, e.g. BAD_REQUEST_BODY or INVALID_MEDIA_TYPE.

You're also able to use response templates to construct payloads that contain detailed errors by using variable substitution from the context of your request.

RESPONSE HANDLING♦️

If you're not using a proxy integration, you need to define mapping responses. These are the counterpart to an integration request in the request flow and transform the backend responses into something API Gateway can handle.

This is also done by using VTL. Additionally, you need to determine if our integration request was successful or if it returned an error - also finding out which exact error occurred.

REQUEST VALIDATION🔍

Validating requests before they hit your integration comes with major benefits of reducing the number of invocations for and saving boilerplate code in your integration.

You're able to do parameter validation (requiring query parameters or headers) as well as payload validation (dedicated models for your incoming request payloads, including the expected content format of payload containments).

MONITORING📊

CloudWatch already tracks a lot of metrics for our API Gateways out of the box, including:

• number of HTTP 4xx and 5xx responses
• execution & integration errors
• integration latency

Besides that, you can enable API Gateway to write logs to CloudWatch which will help you to investigate issues with your integration.

Third-party apps like Dashbird.io help you to monitor all of your REST & HTTP API Gateways with just minimal configuration in a central place - including low noise notifications about issues to your favorite channels.

PROXY INTEGRATION🔌

API Gateway is able to forward your request as is to:

• a Lambda function via a default mapping template or
• an HTTP endpoint - forwarding your entire request

The proxy integration makes API Gateway really easy to use, but remove some of its powerful features.

AWS SERVICE PROXY INTEGRATION🔄

It's also possible to directly integrate your API Gateway to AWS services like DynamoDB, e.g. to insert, update or delete items.

This is useful for simple data ingestion services which then don't require any operations or maintenance.

PRICING💸

Free for the first 12 months - every month - per type:

• REST: 1M API calls
• HTTP: 1M API calls
• WebSockets: 1M messages & 750k connection minutes

ℹ️ REST Gateway is much more expensive than HTTP. Looking at us-east-1, it is $3.5 vs. $1 per 1m requests, meaning HTTP gateway is ~71% cheaper