The first part in a multi part series covering building an API with Amazon’s API Gateway.

This first article covers what features a platform should have to build high quality, future proof, scalable APIs on, relating back to how Amazon’s API Gateway covers our requirements. To be specific, this article will not cover best practices for building a great REST service. That is a large topic in itself.

This is article is intended for an audience with some experience building rest services or APIs. The second part of the tutorial covers Creating Lambda function and Creating API Gateway with Node.js.

Api Gateway Logo

API Development Speed

As Software Developers we want to free up as much time as possible so that we can focus on the core task at hand, building new features. With building APIs, we want to spend as little time as possible worrying about concerns such as performance, security, versions and so on. When we build software, we typically don’t have to think about HTTP and IP protocol concerns such as security (https), packet throttling, http protocol versions and so on. It is all taken care for us by foundational software.

So why not do the same for Web Services / APIs / Web API?

We want a platform that offers as many high quality options for free so that we can focus on building quality software, quickly.


When building an API endpoint, most systems will have endpoints open by default. If someone knows the address, they can make requests to the address. We want to lock who has access and to ensure authentication and authorization on a resource.

API Gateway utilizes Amazon’s IAM security technology to apply specific and granular permissions to the API. What’s more is that these permissions are managed outside of our application, meaning we can grant and revoke permissions through Amazon’s console interface. This means that access can be blocked to everyone unless specifically opted in.

Being able to manage keys and who owns them also gives us visibility into who is using the resource. Drawing from personal experience, I was once asked by a client to deprecate an existing API endpoint. The trouble was, I had no idea who was consuming the service and had no way of notifying them that the service would be turned off in the future.

Amazon's API Gateway Basic Workflow

A simple example of data movement through API Gateway


Throttling is restricting the number of times a request can make a request to an endpoint or resource, in a given time period. For example you might want to only allow a person to request Geocoded data once every 30 seconds.

Some reasons you might want throttling in place could be:

  • Calling a third party API that has costs associated with data transfer or the number of requests
  • To avoid Denial of Service (DOS) attacks that might occur with too many requests
  • To save bandwidth and compute costs

Throttling shouldn’t be something that you should have to go and write code for. In Amazon’s case, it is configured at a method/action/endpoint level in AWS.

Patchwork Application

I coined this name as it represents an application made of lots of different technologies. From a REST point of view, URIs identify unique resources, but the backing technology is irrelevant. Ideally we’d have a system that would allow us to change out the implementation behind a URI, as long as it follows the original contract for inputs and outputs.

Amazon allows us to swap out the backing technology or transform a response into a different format with data transformations. At the time of writing, APIs backed by Lambda technology support:

  • Node.js
  • Python
  • Java
  • C#


As a system evolves, so does the input and output parameters, the trick is not to break the code of people consuming an older API endpoint.  Imagine getting a production outage in your software because the third party service that you are consuming decided to change their input or output parameters without telling you. I’ve seen it happen multiple times before.

The trick is to version the API, so that people opt in to what version they want to consume and as a new version comes out. Existing customers will not be impacted.

The simplest way to visualize this is:

  • /api/v1/data
  • /api/v2/data

API Gateway’s lifecycle management lets us version services as well as offers multiple release stages (think Development, Test, Production).

Caching and Performance

API Gateway caches endpoints which is encouraged. With data that is is infrequently changed have a longer time the cache exists and for data that is frequently changed have a shorter length. For example for chart data that is processed every night, it makes sense to cache it for 24 hours, then to re-build the cache. Use caching wherever possible.

Globally distributed edge servers speed up response time as another benefit of using AWS infrastructure.


The architecture of AWS encourages people to build stateless and non-blocking applications which allows for scalability. API Gateway utilizes Lambda expressions to run code and then interacts with massively scalable storage.


API Gateway provides the ability to enrich an endpoint with self describing documentation.

Extra API Gateway Features

On top of the nice to haves above, Amazon’s API Gateway also gives us:

  • CloudWatch monitoring
  • No need to run a server: Code is deployed as “snippets”, rather than an entire application
  • Testing: The ability to feed a specific endpoint data via the console and review the response
  • Validation: An API can specify a JSON schema to validate requests against (this is done via Models). This means that you can provide a JSON structure to validate a users request against before it is processed. This can be thought of as being Design By Contract for API interfaces.


Amazon’s API Gateway is an impressive product, offering everything required to build a great API. Going forward, we are going to use it to build the services to support a Property Management Software product. Stay tuned for Part 2.

Next Steps

Read Part 2 – Creating Lambda function and Creating API Gateway with Node.js

Amazon API Gateway Example

Please follow and like us: