What does REST APIs mean anyway?

Why I'm talking about this

REST API (or RESTful API) is one of those technical term that is always thrown around when people talk about web dev.

Here, we can use a REST API from openweathermap...
...make sure that your APIs are RESTful...
Cat-as-a-Service is a RESTful API service...

It's not really a problem when you are casually learning, until you have to hit StackOverflow (which is basically everyday):

I'm not sure if this way of doing stuff is RESTful.
Your API is not RESTful, fix that.

In a spree of Google searches, you opened (yet) another tab and started looking up what is REST. And all you get after getting dangerously near to the limits of your poor RAM is some techobabble mumbo jumbo. Making the matter worse is that English is in fact, my second language. (I thrived writing blogs with online grammar checkers, super helpful).

At least those are my experiences, and here I would like to rephrase them with extra clarity. We will go phrase by phrase, and clarify them one part at a time.

Let's start with APIs

API stands for application programming interface. Let's see what we can do with this.

You can also define APIs as interfaces for programming applications. Compare that with user interface, an interface for users.

For non-English natives, interface is the point where two systems meet.

All in all, the "verbose" definition of API is a point where two applications meet, and developers may use this point to do certain functions.

In the case of web development, an API is often referring to a URL that returns JSON instead of a webpage. That URL is the endpoint of the API. A refresher for you: URL means Uniform Resource Locator.

The URL functions as an identifier for its resource. In a sense, resources are the "name" part of the name-value (or key-value) pair. Each resource would have its state, which is the "value" part.

For example, let's say you are calling an API to request the latest weather info in Germany, and the API returns "raining".
The URL of the API is the identifier of your resource (that is, latest weather info in Germany). And the state of the resource is its response (that is, raining).

So what's REST

REST stands for representational state transfer. And what the heck is that?

REST is simply a software architecture, a set of rules on how the software should behave, and what to expect from them. They don't care how you implement them, as long as it follows these rules, or rather, constraints.

When calling an API, you give the server the exact URL and the HTTP method. The server receives this request, read from a database, do a sprinkle of processing, and return them to you in the form of JSON (although they can also return XML or HTML).

So the whole exchange is, at a fundamental level, a transfer of information. And the server transfer a representation of the state of the requested resource.

What is the representation of state here? It's the format in which it is transferred, be it JSON, XML, or HTML.

Now, let's talk about the constraints that an API has to follow to be considered RESTful.

How to be RESTful

Have a uniform interface

This one has 4 parts:

1. The API request must include the resource identifier (a unique subdirectory, an attribute, etc.)

2. The response should be enough for the client to modify the resource

3. The request & response should be complete; the request have all the info needed for the server to process, and the response have all the data requested.

4. The response need to also inform clients of possible ways to change the state of resources. For example, if you request for the name of the latest US president, the response should also includes methods to change that name. Obviously that's absurd, but that's the situation of most public APIs today. They usually serve data that are not meant to be changed by the user. As such, a lot of public APIs are not actually RESTful.

Only between independent servers and clients

This info transfer is based on requests. A client only needs to request some data, and the server only response when it received the request. A server should not send a response without any request.

Does not store sessions (stateless)

In a RESTful API, a server has no idea about the previous requests of a client. Its response is not affected by other requests made by a client, as each request must have enough info for the server to work with.

Able to be layered

In a perfect world, there is a direct connection from a client to a server. But in reality, system admins might implement a VPN for security, or caching servers in between. A RESTful API shouldn't give a f*ck about that.

Able to be cached

The info that a server send should be cacheable. It is important that the client knows if their data is stale, so that they can request the latest one.

Able to send Code-on-demand (optional)

Basically, a RESTful API can send a working code to the client for the client to execute. A common example of this is webpages (the server returns a render-able HTML page). But it's optional, why bother?

Closing words

Lately, I have little time to polish my blogs, and while I like to maintain their quality, consistency is still a big part of it. I'm sorry if this particular piece is not living to your standard, based on my previous works.