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!

Website up!

These days it is a 5 minutes step to have a professional website up and running. I decided I would configure everything from the ground up to gain more practice with the tools and technologies that are normally automatically configured for us.

Step #1 – My domain and Route53

I had already bought a domain jfalco.com in Route53 but it was not being routed anywhere yet. I followed this guide to forward the jfalco.com traffic to the EC2 instance.

  • Created an A record http://www.jfalco.com that pointed to the EC2 instance IP. Wait! Isn’t http://www.jfalco.com different than jfalco.com? I tried to access my EC2 instance through my newly configured domain but my browser kept returning “This site can’t be reached – ERR_NAME_RESOLUTION_FAILED”. What?! But I just configured the route! Maybe it has not propagated yet, it being the cloud and all… Waited a good 20minutes and still would not budge.
  • After a lot of reading and googling, turns out my jfalco.com name servers were different than my hosted zones name servers. Doh! I made the assumption Route53 would automatically use the same name servers as my domain given that I literally created the hosted zone by clicking on my domain through the Route53 console. I copy pasted my hosted zones name servers to my domain name servers and it took roughly 30 seconds to start working. I also added a tiny CNAME record to link jfalco.com to http://www.jfalco.com. Woot! My domain is finally pointing to my website!

Step #2 – EC2, Tomcat8 and the actual content of the Website

  • Previously I had very hastily installed tomcat8 just to make sure my EC2 instance could be accessed. Now I had to make the real configuration and deploy my war file. First, I moved the manager app outside of the root and very quickly found the configuration I required to make my war be the root as well as change the port to be 80 instead of :8080; it would not look very good if people had to type http://www.jfalco.com:8080/mywebsite.
  • To make the war be root, the war file has to be named ROOT.war and the folder with the content has to also be named ROOT.
  • To change the port to be :80, the file ‘server.xml’ in the tomcat8/conf folder needs to have the changes for port :80.
<Connector port="80" protocol="HTTP/1.1"
 redirectPort="8443" />
  • Also had to change users to secure access.

The Website

  • Using Java EE I went ahead to setup my project in Eclipse. First hurdle, how do I configure the web.xml to serve the content of my website? At first I tried

And that did work with my <html><body>Hello, World!</body></html>, but failed once I tried to serve any CSS, JS or image file.

  • One more thing to note in here is that the html files need to be at the root of the WebContent folder, right above WEB-INF.
  • Turns out I did not need any servlet mappings yet.
<welcome-file-list><welcome-file-list> <welcome-file>index.html</welcome-file> <welcome-file>index.htm</welcome-file> <welcome-file>index.jsp</welcome-file> <welcome-file>default.html</welcome-file> <welcome-file>default.htm</welcome-file> <welcome-file>default.jsp</welcome-file> </welcome-file-list>

Was all I needed.

  • Great, now to the actual development of the content. Since I am doing everything from scratch I want to leverage on some frameworks, that will also help me learn. ReactJS + Typescript + bootstrap + LESS or SASS and a package manager like npm? Maybe I could use AngularJS? What about the testing frameworks? Wait… I need to take a step back. Do I really need all this complexity? I am going to have a very simple home page with some of my information and the blog is currently hosted in wordpress, so… Maybe I just need bootstrap  to make my CSS life easier and npm to make packaging slightly easier.
  • My initial setup includes jquery and bootstrap. I created a very simple introductory home page that needs more styling but its not terrible. I think its a good start and I finally have my landing page that gives me an online presence. I have a ton of plans for that website, but one step at a time.

A lot of good lessons learnt in here: how to configure name servers in Route53; a good tomcat8 installation in EC2 that displays the WAR file at the root level; and refreshing those web development skills. I am not happy with the theme yet but its something.