HomeAboutContact
Programming
What The Heck is a RESTful API, Anyways?
April 19, 2020
7 min

Table Of Contents

01
The Web
02
GET
03
POST
04
PUT
05
PATCH
06
DELETE
07
REST
08
LEVEL 0: The Swamp of POX
09
LEVEL 1: Resource Based Address/URI
10
LEVEL 2: HTTP Protocol
11
LEVEL 3: HATEOAS

If I were to take myself back to the days when I first started diving into the world of development, I remember being baffled by the term RESTful and as far as I was concerned, API was just a URL that I would use in my JavaScript application in order to fetch some data from an external resource.

After a while I started wondering how that data was actually being delivered to me. It wasn’t making a lot of sense because usually URLs would just take me to a website, but the API URLs would actually give me an object (a JSON object, to be exact).

So then I decided to put my thinking hat on and start the research. Below, are all the essential information I’ve gathered and learned about RESTful APIs.

The Web

It’s important to understand the way the web works when it comes to understanding, designing and building APIs. In its most fundamental form, the internet is just made up of requests. For example, as a user you’d make a request to a server. This might be for a web page, an API, a JavaScript file, an image, etc. The request itself is made up of three pieces, a verb, which is what you want to do, the headers, which include additional information, and then the actual content. In the case of a simple request for a web page, the content might actually be missing.

GET

The most common of these requests is GET. Hey server, I want you to give me something that you have. This request is used retrieve a resource from a server. You can think about a GET as hey server, please give me this webpage or hey server, please give me this image and so on.

POST

POST adds a new resource. So POST says hey server, go create me a new one of these. With this request we usually also provide some data that’s related to the new object that we wish to create on the server.

PUT

The PUT verb updates an existing resource. So essentially it says here’s the data that I may have retrieved from you earlier with some changes, please update the what’s currently on there, with these new changes, kind server.

PATCH

PATCH is something that’s not as commonly used, and while it’s kind of similar to PUT, the main difference between them is in the way that the server processes the enclosed entity-data to modify the resource. In the PUT request, the data we’re sending to the server, as far as the server is concerned, might be completely different than what the previous resource was, while a PATCH requests contains a set of instruction describing how the resource that is currently residing on the server should be modified to produce a new version. Also, another difference is that when you want to update a resource with a PUT request, you have to send the full payload as the request, whereas with PATCH you only send the parameters which you want to update.

DELETE

And lastly, DELETE which does exactly what the name suggests, it deletes a specific resource on the server.

There are actually more HTTP request methods than the ones listed here, but these are the most common. For a full list of all the HTTP request methods that goes more in depth in to what each of them does, click here.

That’s all fine and all, but I still have no idea what the heck is a RESTful API!

I hear ya, but if you’ve been reading up to this point, then you’ve pretty much got all the basics down. REST is nothing more than standards.

REST

REST stands for REpresentational State Transfer and it’s basically an architectural style for providing certain standards (or constraints, depending on how you see it) in the communication between computer systems on the web. When a system or an API is compliant to these standards, we call that a RESTful API.

Some of these standards are:

Client-server architectureSeparation of concerns, I’m sure we’ve all heard that before. In this case, we’re referring to the decoupling of the user interface from the server, the separation of the client data from the server data which improves the portability of components.

Statelessness. All the requests and client-server communication is stateless, meaning that no client data will be stored on the server and all of the session state is stored on the client

Cacheability. The client should be able to cache requests (similar to how the browsers caches static elements, such as images, of a web page) in order to improve performance

Uniform Interface. Probably the most fundamental REST standard, saying that all requests should use a URI or Unique Resource Identifier.

When we’re talking about REST, we’re usually referring to URIthat needs to be pointing at a resource. So when a user, the client, wishes to access something on our web page, the API should be designed in such a way that it provides a unique address that leads to that resource. Let’s assume an example of a very simple website (https://example.com) with two pages, a home page and a profile page. Usually homepages can either be accessed by appending an /index.html at the end of the URL, or a lot of the time we can even ignore that and just access it with just https://example.com. And this is where I ask you to create your own URL for accessing the profile page. Go ahead, I’ll give you a minute to think about how you’d want it to look like. Done? Alright. This is what mine would look like https://example.com/profile. If what you thought of is anything close to mine, then congratulations, you just formed your first URI/profile/home/users, /cart, those are all URIs, they’re paths that lead to certain content on our web page. URIs should also be self-descriptive*, so that if we’re consuming an API and come across a URI that looks like /api/users or /api/cart* we should instantly know what data to expect from each of those.

Do I have to follow all these standards when I’m designing an API?

Yes, and no. When designing your API you can chose to follow all of the REST standards or maybe you can just follow some of them. But in the case where you to chose to follow only some of them, would your API be considered RESTfulOr partially RESTfulHere’s where the Richardson Maturity Model comes in. According to the Richardson Maturity Model, any API can be assigned into one of the following maturity levels.

LEVEL 0: The Swamp of POX

At this level APIs are not considered at all RESTful, and in the communication between the server and the client there is only one address, there is no concept of URIs and no proper use of the HTTP Protocol, everything is defined by XML and in the case of SOAP web services that is called POX (Plain Old XML).

LEVEL 1: Resource Based Address/URI

The very starting level of RESTful APIs. It’s concept, as I previously discussed, is based upon having unique addresses-paths that lead to different resources on the server unlike the previous level where we only had a single URI.

LEVEL 2: HTTP Protocol

This where the HTTP verbs comes in. In comparison to APIs on level 0, that have no usage of VERBS, and level 1, that only make use of the GET or POST verbs, APIs on this level should be using all of the HTTP verbs (PUT, DELETE, PATCH etc.)

LEVEL 3: HATEOAS

HATEOAS stands for Hypermedia As The Engine Of State and APIs on this level are considered to be fully RESTful APIs. A level 3 RESTful API has multiple unique, self-descriptive URIs, makes use of HTTP verbs and the response includes hypermedia links that provides additional information to the user or developer who’s consuming that API.

Wait, what do you mean?

Here, let me give you an example. Let’s assume we have the following endpoint : https://example.com/customers/5

Sending a GET request to that URL would give us back the data that’s associated of the customer that has the id 5. A level 2 mature API would give us back the following response :

{
  "firstName": "John",
  "lastName": "Doe",
  "age": "25"
}

But in the case of a level 3 API we’d receive a response along these lines :

{
  "firstName": "John",
  "lastName": "Doe",
  "age": "25",
  "links": [
    {
      "rel": "self",
      "href": "https://example.com/customer/5",
      "method": "PUT"
    },
    {
      "rel": "self",
      "href": "https://example.com/customer/5",
      "method": "DELETE"
    },
    {
      "rel": "orders",
      "href": "https://example.com/customer/5/orders",
      "method": "GET"
    }
  ]
}

As you can see, while the data that‘s related to the customer may not have changed, we’ve also received a list of (hypermedia) links that pretty much tells us everything we need to know about the API without us having to go through the documentation to find all the possible capabilities of it.

Before I end, I’d like to let you know about one last thing that I forgot to mention earlier. URIs often contain (optional) parameters that you can pass with the endpoint in order to influence the response (affect the number of results that will be retrieved, sort order, type of response etc.). There are four types of parameters :

Header parameters, which are included inside the header of the request. Usually these refer to authentication, and while I know that I didn’t get to touch on what headers are, since that subject can get pretty low-level, maybe in the future I will dedicate a whole article about headers and authentication.

Path parameters, are included in the path and are used when we’re requesting something specific on the server. These parameters are not optional and are usually a part of the URI. We used one earlier when we were requesting data specifically for the user with the id of 5 (https://example.com/customer/5).

Query String parameters, which are also included in the path of the request but are optional and if present, they get appended at the end of the URI after a question mark (?). If there are multiple query strings, they are chained together with an ampersand (&). The order of the query strings does not matter. An example would be https://example.com/customers?blocked=true&results=20 and that should give us a list of all the customers that are blocked and results should be limited to a maximum of twenty.

And last but not least, Request Body parameters which are included in the body of the request, usually in a JSON format and are frequently used with POST requests.

Personally, I wouldn’t stress or worry too much about trying to include all those standards when you’re first starting to create APIs, what’s important is to communicate clearly, to the developers who are consuming your API, what its capabilities are, even if that means being a little more pragmatic about it and not checking off everything from that list.

https://miro.medium.com/max/1184/1*WRFc2G9kgxZoqYdpsmwV2A.png

If you’re reading this then that means that you stuck with me all the way ‘till the end, that’s awesome! Thank you for taking the time to read through all that, it took me quite some time to put everything together and I really do hope this post helps people understand RESTful APIs, even a little, better. Happy coding, everybody!


Related Posts

The Complete Guide on Becoming a Developer in 2022
January 12, 2022
13 min

Matheo Dodi

© 2022, All Rights Reserved.

Quick Links

HomeAboutContact

Social Media