Understanding AWS – API Gateway

API Gateway is a service from AWS that provides a ReSTful interface between a client/requester and an endpoint.

The term client/requester and endpoint are abstracted on purpose because it can literally be anything that can send or receive an HTTP/HTTPs request.

Another concept that is hard to define is “ReSTful”. Recently I realized I could not really define what restful really meant; I could briefly mention characteristics about it, but not really dive deep into it, even though I have been using it for years.

Note to myself – restful interfaces are a style of sending or receiving http requests. It is a “style” because the request will not actually break or not work if it is not sent in a restful manner.

The client:

  • Describes where the request is going via a URL.
  • Controls the request with headers.
  • Sends additional data via: query string parameters and the body (for methods that allow it). Additional data can also be sent via the headers, but they are mostly meant for control.
It is important to note why "control with headers" is done via the client 
and not the server. The server does not make any assumptions about the
request; it can enforce rules (example: authorization), but does not make 
assumptions. This allows the server to have more flexibility with each 
request it receives. In this case the server/interface is API Gateway.


  • What the endpoint has to do will depend a lot on the particular endpoint.
  • Examples of endpoints: HTTPAWS Lambda, a database, a mail server, a queue. Note that the endpoint does not have to understand anything about restful APIs, because another service (API Gateway) has abstracted that for us.
  • The endpoint does have to return a status code or the interface will assume there was an error. Additionally the endpoint can return more information if the interface allows it.

What else can be said about a restful request?

The style also uses resources and methods/verbs to describe the actions you are trying to do.

The request

For example the URL: https://httpbin.org/ip contains several parts that describe our request:

  • https – describes the protocol the request is trying to use.
  • httpbin.org – is the domain that gets asked to a name server to try to find the IP that can (hopefully) serve the request.
  • /ip – is a resource that describes what are we trying to access under that domain.
  • We do not get to see it in the URL, but the resource is tied to verbs or methods. In this case it is a GET method. Notice also how it is very easy to describe what that URL is trying to accomplish by reading it with simple english words: use the https protocol to GET the ip. If we were super strict it would be GET the ip of the httpbin.org domain. But in reality this request returns the IP of the client.
  • There are also headers that automatically get sent even though we do not specify any. host and accept, are two very common headers.
  • The request does not contain a body. How do I know that? Because it is a GET method. The standard does not actually say the GET method does not need to contain a body, but in this restful style we are adhering to the verbs. GET is a verb used to retrieve something, and the same request should always return the same thing; if we send data in the body then we allow data to control what is going to be returned and loses the style.

Note to myself – a restful interface defines the following verbs: GET, POST, PUT, DELETE, PATCH, HEAD and OPTIONS.

The response

In the simplest response, the client really only needs a status code, to know the status of what happened with the request. Of course, it gets more complicated because the response could also have a body and headers. And each header means something different.

For example: when a website is opened like ‘https://httpbin.org/’, the client is actually making a GET request to (usually) an HTML page. The response contains a very important header: ‘Content-Type’, without it your page would not even render because the browser would not know how to interpret the document.

Phew! That was a lot of information!

So, with all the previous data, it is easier to appreciate what API Gateway does for us. It makes it very easy to process a restful request, send it to an endpoint and respond to the client. It is very interesting also because API Gateway allows us to customize every single process of the request and response. It even allows us to completely customize the errors.

Further deep diving into API Gateway in future posts!