Understanding RESTful APIs pt 1

Understanding RESTful APIs pt 1

(or How RESTful APIs came to be)

Are you starting with web development? Have you heard about RESTful APIs? Web developers should have a clear understanding of what RESTful APIs are, for they have become one of the foundations of modern web applications.

In this series, I will share with you everything I know about RESTful APIs: from what they are and why they came to be, to how they work and why they are so convenient for building anything from small websites to entire platforms.

If you aim to create useful APIs or want to make the most out of the ones already out there, I invite you to read on!

Versión en español

Part 1: How RESTful APIs came to be

The beginning (or REST: a bit of history)

Before RESTful APIs, there was REST; before REST, there had to be... chaos!

Back in the 90s, the number of users surfing the World Wide Web saw a rapid increase. The Internet was the new kid on the block and everyone was loving it!

Everyone, except programmers.

The development of general-purpose websites suddenly became a demanding occupation. Sooner than later, the huge growth of the web ecosystem made a big problem clear: there weren't well-defined, standardized ways of building and communicating applications throughout the Internet.

Luckily, several nice folks began working on this, consolidating some of the most fundamental standards of the web. One such folk, Roy Thomas Fielding, who was part of the team that specified the standards of HTTP 1.0 and 1.1, started working on a thesis about an architectural style for building and communicating systems on the Internet.

Enter REST.

Going RESTful! (or REST: a definition)

Fielding presented his dissertation "Architectural Styles and the Design of Network-based Software Architectures" in 2000. There, he defined the Representational State Transfer (REST) architectural style as a set of constraints: a sort of guide for designing and building systems over the Internet.

We can say that REST is more about defining how to do things (an architectural style), rather than representing an implementation by itself.

Every piece of software that follows (all or most of) the constraints defined by the REST architectural style (aka every implementation of REST) is... drum roll... RESTful!

But, what are those so-called constraints defined by REST anyway? I'm glad you asked! Let's talk about the 6 constraints that every RESTful implementation should follow:

  1. Client-Server. This is our starting point: how the architecture should be. Following a client-server architecture, we must separate the user interface concerns (the client) from the data storage concerns (the server). This separation will allow every component (client or server) to evolve independently, thus, providing portability and scalability.

  2. Stateless. Having defined a client-server architecture, this second constraint states that the communication between the client and the server must be stateless: every request made by the client must contain all the information needed by the server to process it. Requests cannot rely on any context on the server: they must be independent.

  3. Cache. As a nice complement to the stateless communication between clients and servers, the cache constraint lets us tag certain resources returned by the server as cacheable or non-cacheable. A cacheable resource can be safely reused by the client for identical requests later on. This can improve speed and efficiency by reducing the number of interactions between the client and the server.

  4. Uniform Interface. This is the constraint that differentiates REST from other architectural styles. It tells us that, regardless of what resources the server is providing, there must always be a uniform interface that defines how these resources are presented and, thus, how they should be consumed by the clients. This uniform interface is, in turn, defined by four constraints:

    • Identification of resources: Every resource must be identifiable by a unique ID.

    • Manipulation of resources through representations: A client should be able to manipulate resources through their representations returned by the server.

    • Self-descriptive messages: Interactions between client and server should provide enough information (media-type, HTTP verb, etc.) to make clear the intention of the request.

    • Hypermedia as the engine of application state: Hypertext/hyperlinks provided by the server as part of the responses should specify what can be performed next for any given resource.

  5. Layered System. This constraint allows us to break the architecture into separate layers with a specific task each. Every layer is independent and knows nothing beyond the immediate layer they interact with. With this in mind, we can have a layer for managing authorization, for example; another one for load balancing, and so on. This also provides portability and scalability for each component on the layered system.

  6. Code-On-Demand. This last constraint is an optional one. It provides the client with the possibility to extend its functionality by downloading and executing code in the form of applets or scripts. This allows the clients to be more lightweight by reducing the features implemented directly on them.

Now that we know what RESTful means, we are ready to talk about APIs, RESTful APIs!

Defining RESTful APIs (or what you came for, finally!)

We're almost there!

With a clear idea of what REST is and what RESTful means, there's only one last bit we need to clarify: what are APIs?

An Application Programming Interface (API) is a set of rules that define how two pieces of software must communicate with each other. We can see it as a sort of contract that each part has to follow to transfer data between them.

Cool! Now we have a decent understanding of all the concepts we need to finally define a RESTful API!

Here's a simple definition:

A RESTful API is a way of communicating two applications over the Internet under the constraints defined by REST. In other words, RESTful APIs are a way to define how web services present their resources and how clients should consume those resources over the Internet.

Graphical representation of an API

So, although not exactly a standard, this implementation of REST in the form of APIs was a solution to the problem of communicating applications over the Internet. Not the only solution, though: SOAP, for instance, was already out there by the time RESTful APIs came out. But that's a story for another article...

What's next? (or How RESTful APIs work)

For the next part of the series, I'm planning on presenting a deeper explanation of how these APIs work: I'll write about how they stick to the REST constraints mentioned before, including concepts like resources, HTTP methods, etc., so that you can actually consume or even create your RESTful APIs.

I will finally end this series with a brief conclusion on why RESTful APIs are so useful nowadays. Should you always use them? Should you not?


I hope this article helped you have a better idea of what a RESTful API is. If you have any comments or thoughts on this article or if you have a specific topic you'd like me to write about, please let me know!

Thank you so much for reading this far! Have a great day!

All images used in this article, including the cover, were designed specifically for this blog by Zafiro Luna.

Did you find this article valuable?

Support Ricardo Mendoza by becoming a sponsor. Any amount is appreciated!