What is an API?

Well first, an API is an “Application Programming Interface”, and it is a way for one application to “talk” to another. Of course, you have to speak the same language ( .json , .csv , .txt ). And it is through API’s that most web applications are built. So if you want to do full-stack engineering, you need to know API’s.

My goal here is to share the concepts that I believe are key to understanding API’s in Ruby. I am sure that there are many tutorials that will show you exactly how to do it, so I will not re-hash that here; here my goal is to help you understand how an API works conceptually.

The trick to forgetting the big picture is to look at everything close-up. - Chuck Palahniuk

1. Programming Paradigms
2. Model View Controller
3. Web Concepts
4. HTTP Requests
5. Routing
6. Rendering
7. Static
8. Dynamic

Model View Controller

Starting if with a definition; Model-View-Controller or MVC is an architectural software engineering design pattern in which we decouple different functions of an application or in programmer talk - separate our concerns. In this case; we are separating the concerns of modeling data into three broad categories;

1.Model - as a verb it would be “modeling”, this functional group is responsible for “modeling” or data. These are the objects that hold and organize our data.

1. Controller - as the name implies, this functional layer serves as a sort of router, designated the responsibility of communicating with the models to work with the application data.
2. View - the view assumes responsibility of displaying content to a user by interpreting the information received from the controller.

It is key to understand the distinctions here; a view is only responsible for display functions, a model is responsible for representing our data, and a controller contains the logic for interaction between the two other layers.

HTTP and the Internet

HTTP stands for Hyper-text transport protocol (a web communication protocol) and is the standard along with HTTPS or Hyper-text transport protocol secure. In programming lingo; think of HTTP as an object that has methods and functions that allow us to send messages and read messages over the internet.

Like most things in the world of systems, there are pieces to an HTTP command; a header, a body, and a footer. The header will have things like who sent the request, what type of request it is (more on that later), the path of the resource they wish to issue the command to, and more, but those are they key things. Next there’s the body, which will have the “payload” of the command, and lastly there is a footer that denotes that that is the end of the HTTP command.

Starting with the types of HTTP; there are a few core types that mirror CRUD (create, read, update and delete) functions.

In HTTP lingo;
• "create" would correspond to a PUT HTTP command.

• "read" would correspond to a GET HTTP command.
• "update" would correspond to a PATCH HTTP command.
• "delete" would correspond to the DELETE HTTP command.

There are additional (less common) types of HTTP commands like;
• TRACE , which will echo back the last received request
• OPTIONS , which will return the HTTP methods supported by the server
• CONNECT , which will convert the command to a TCP/IP tunnel (generally for SSL)
• HEAD , which asks for a response (like a GET but without the body)

These allow servers to send and retrieve information and are the key building blocks of API’s.

Routing

The next fundamental concepts of Ruby API’s is the concept of routing. Personally, I like to think of Routing just like a network router that most of us have in our home. It takes a HTTP command (or request) and directs it to the appropriate resource. However, unlike network switches/routers, Ruby routes, referring to directing traffic from an endpoint which is how most websites work.

When you go to http://www.cnn.com/, your browser is sending a GET request to that DNS (Domain Naming Service) resolves that to an IP address, which your browser then sends an HTTP GET command. In this case, no authentication is required, and the website responds with and HTTP response (request --> response) whose body (think "payload") carries the HTML from the requested page.

In the example of cnn.com, routing was implied: since nothing followed the .com, we simply wanted the index page. When you want to go to a more specific resource at that IP address like https://www.cnn.com/us... the traffic will be directed by DNS to the same server, however that server will respond different as the GET command has refined the information it is requesting . This is the fundamental concept of routing. It involves interpreting an HTTP request and directing it to a controller which can process that request.

Rendering

Let’s start with a definition; [technopedia’s(https://www.techopedia.com/definition/9163/rendering) definition was the first one I found that I felt concisely describes rendering in the context of the web:

Rendering is the process involved in the generation of a two-dimensional or three-dimensional image from a model by means of application programs

Here, what I am referring to by "rendering" is the act of interpreting web code (most commonly in the form of HTML, CSS and JavaScript) and generating or retrieving the requested information.

In the case of web applications, it can be as simple as delivering an HTML page. This is typically referred to as static rendering. Well this works fine for “about us” pages, more elaborate sites will display different depending on a variety of factors, this we call dynamic rendering.

Putting it all together

So now that we understand how the internet works (HTTP commands, requests and responses) and how those requests are routed and rendered. Let’s put all those pieces together and talk about how it fits into the MVC software design pattern and more specifically Ruby (on Rails).

At a high level, an HTTP GET command is sent to a web resource, requesting to read data. That resources processes HTTP command/request and routes it to the appropriate resource. Assuming the requestor has adequate permissions, the resource will then pull up (think “read”) the requested information with an HTTP response and the body of the HTTP response will have the payload or information requested by the user.

Now let’s put that in context of MVC and Ruby on Rails with an example:

A resources makes a HTTP GET command to a resource we will call myapp.com . That resources receives the requests and routes the traffic based upon the directions supplied in the routing file (routes.rb).

The routes file describes what to do depending on the request. Here we are requesting (GET) a document called ’myapp.com/about’ which in Rails means that I want to GET or “read” data from the “about” page. In this example, I am simply going to pass this to a StaticContoller by directing the traffic to: static#about , which says
pass this traffic “to the StaticContoller and call the about method" (or “action” in Rails lingo). and passes the HTTP command onto the relevant controller (the “C” in MVC).

The controllers job is to process that request by using the Models to represent application data and then call upon a View to display that data to the user complete with the information requested with the initial HTTP command.

There’s a lot more to understanding how this works, as Rails is a framework that is built leveraging conventions (marketed as “convention over configuration”), which simply means that these pieces are all “wired” together based on naming conventions.

How does this all fit in with APIs?

In the case of Rails applications, all of the above process holds true, but we exclude the “View” part (mostly). In the case of an API, another application is requesting information, and the job of the API is to return that information in a mutually agreed upon language; which in most cases in json.

Here if we are making a HTTP GET request, we want to “read” information; so the Rails application would still be routing that request to a controller, and the controller would still be interacting with one or more of the application models, but the last part differs. Unlike a standard web page, an API request would be expecting different content in the body of the HTTP response, which is often text formatted as JSON or (JavaScript Object Notation). In other words, the “View” here would be simply JSON data, no HTML or CSS.