Davide's Code and Architecture Notes - Web APIs vs REST APIs vs pseudo-REST APIs

When describing a web service, people often use the wrong terms. Are you really creating a REST API, or is it some sort of pseudo-REST?

Table of Contents

Just a second! 🫷
If you are here, it means that you are a software developer. So, you know that storage, networking, and domain management have a cost .

If you want to support this blog, please ensure that you have disabled the adblocker for this site. I configured Google AdSense to show as few ADS as possible - I don't want to bother you with lots of ads, but I still need to add some to pay for the resources for my site.

Thank you for your understanding.
- Davide

The first version of this article contained a lot of misinterpretations of what REST means, including the fact that REST and RESTful are separate things. A huge thanks to Andrea Chiarelli for pointing it out. I had to rewrite the article almost thoroughly in order to remove all the confusion I tried to clear out, but instead, I helped spread.

In a world full of acronyms and terms, some nuances can get lost.

People claim they’re developing REST APIs even though their APIs do not follow the REST principles. Maybe their APIs are inspired by REST principles, but they are still not REST APIs.

In this article, we will explain the differences and similarities between “simple” WEB APIs, REST APIs, and pseudo-REST APIS, and you will learn that most probably you are not exposing “real” REST APIs.

What are Web APIs?

API stands for Application Programming Interface. It’s a common term that indicates how to interact with a system by specifying its list of operations, inputs, and outputs.

A specific type of API is the Web API: a Web API is an interface that allows communication between different software applications over the web.

Communication occurs via HTTP or HTTPS, and data can be exchanged in several formats, such as JSON, XML, or even plain text.

Not every Web API is also a REST API: we’ll learn why in a second.

What are REST APIs?

In REST APIs, everything revolves around the idea of a resource: your APIs do not expose endpoints that represent generic operations (/getItem), but using a combination of URL and HTTP method, you can define everything you can do with a resource.

REST is an architectural pattern that, to be followed, requires you to follow some principles:

• Statelessness: Each request from the client must contain all necessary information; the server doesn’t store the client state. There is no context shared across different requests, making the system easier to scale and maintain.
• Cacheability: Responses can be cached to improve performance. You can use the ETag header to understand whether the cache is valid.
• Resource-Based: REST APIs expose resource operations via URL, and clients interact with these resources using standard HTTP methods. Each HTTP method has a specific meaning (so, put short, if you are using a POST to retrieve an entity’s information, you are not adhering to the REST guidelines)
• Uniform Interface: Resources are exposed via a consistent representation (using URLs). In general, you want your URLs to be structured like /{resource-type}/{id}; for example, information about the book with ID 555 should be retrieved at the URL /book/555 (notice that it’s book, singular, and not books).
• Operations via HTTP methods: You must use standard HTTP methods (GET, POST, PUT, DELETE) to represent the operations on a resource. For example, with GET you retrieve information, while with DELETE you only delete an entity. You must not use GET to delete a resource.

REST is an acronym that means “REpresentational State Transfer”. Let’s focus on each word of the acronym.

“RE” stands for REpresentational: this means that you are not accessing the resources directly, but you are referring to a representation of such entities. Working with representations and not with direct access allows you to decouple client and server, bringing also the benefit of scalability.

“ST” stands for State Transfer: your APIs must include all the information to retrieve everything correlated to the resource in a self-explaining way. For example, suppose that you have a GET /book/42. This endpoint should return something like:

{
  "id": 42,
  "title": "The Hitchhiker's Guide to the Galaxy",
  "authorName": "Douglas Adams",
  "publicationYear": 1979,
  "genre": "comedy",
  "links": [
    {
      "href": "https://api.mylibrary.com/book/42",
      "rel": "self"
    },
    {
      "href": "https://api.mylibrary.com/author/123",
      "rel": "author"
    },
    {
      "href": "https://api.mylibrary.com/genres/861",
      "rel": "genre"
    }
  ]
}

This list of endpoints stored in the links section allows clients to navigate to the details of the entities related to this book. These links form the so-called HATEOAS (Hypermedia as the Engine of Application State), and allow clients to navigate to all the entities related to the retrieved one without having previous knowledge of the other endpoints exposed by the system.

HATEOAS is a fundamental part of REST, since it allows clients to access the state of the resource (remember the “S” in “REST”?).

It’s worth noting that HATEOAS should start from the root. Just by providing the root URL, the client should be able to understand which entities are available and navigate the hierarchy of resources dynamically.

For example, by accessing the root URL of the system (for example, https://api.mylibrary.com) you should be able to retrieve the list of the available types of entity (book, author, genres), making your clients able to know everything they need just by accessing the root URL.

As stated by Roy Fielding, the creator of REST, in an article on his blog:

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations.

What are pseudo-REST APIs?

The harsh reality is that most of us write pseudo-REST APIs.

Most teams develop the usual type of APIs using some REST practices but do not thoroughly implement the architectural pattern.

I bet most of you use HTTP Verbs to perform CRUD operations on your entity.

But I can also imagine that you don’t implement HATEOAS and don’t provide content negotiation.

The truth is that you create a REST API, or you don’t. There is no such thing as REST-ish API.

Further readings

REST APIs were first described by Dr Roy Fielding in his doctorial dissertation. The original paper is available online:

🔗 Architectural Styles and the Design of Network-based Software Architectures | Roy Thomas Fielding

This article first appeared on Code4IT 🐧

When you create a resource using REST APIs, you should also return the reference to the details of the newly created resource. In ASP.NET, it’s easy: you can use CreatedAtAction and CreatedAtRoute.

🔗 Getting resource location with CreatedAtAction and CreatedAtRoute action results | Code4IT

Andrea Chiarelli, who helped me understand that the first version of this article was wrong and misleading, wrote a great article explaining what REST really means.

🔗 Please, don’t call them RESTful | Andrea Chiarelli

Wrapping up

Understanding the correct terminology helps us use a shared language, avoiding misunderstandings.

Even if you don’t need to know all the details of the REST principles, it’s important to at least know that not all Web APIs are REST APIs.

I hope you enjoyed this article! Let’s keep in touch on Twitter or LinkedIn! 🤜🤛

Happy coding!

🐧

A final personal note

As I wrote at the beginning of this article, the first version of this blog post, instead of clarifying what is and what is not REST, helped spread misinformation.

Unfortunately, online, there is so much content that explains that REST and RESTful APIs are separate things, some sort of “RESTful is a REST API with all the parts implemented”, that I fell into the trap as well.

I apologize to all of you, my dear readers. I will do my best to avoid a situation like this will happen again, studying even more before writing my articles.

Again, a huge thank you to Andrea. I invite you to comment on my (and others’) articles and videos to tell when we are wrong - one of the reasons I write is to clear my mind around certain topics, and having people correcting you is a great way to learn.

Sorry again, Davide