This page looks best with JavaScript enabled

What Does a True RESTful API Means?

 ·   ·  ☕ 4 min read

Introduction

The way we used to deliver resources to the client in a server-client setup is now drifting away from REST to a more modern delivery mechanism. Two of them are gRPC and GraphQL. While both these solve a different kind of problem, REST is going to stay for a while. It is the simplest to learn at least.

You might have seen job descriptions requiring skills like the ability to design RESTful API. What does it mean by RESTful API?

There are libraries made around this “RESTful”. One of them I have used in the past is Flask-RESTful. But let’s talk about what RESTful API really is for a good understanding.

So RESTful API is a result of a software architectural style that defines a set of constraints to be used for creating Web services. There are 6 guiding principle which makes RESTful APIs. It isn’t that our servers and client won’t work if we don’t follow these principles; it will make sure we stay on the same page like others.

The guiding principles are:

1. Client-server architecture

This constraint essentially means that client application and server application MUST be able to evolve separately without any dependency on each other. A client should know only resource URIs, and that’s all. Versioning can be used for breaking changes.

2. Statelessness

All client-server interactions are stateless. There are no sessions are to be maintained. The server will not store anything about the latest HTTP request the client made. It will treat every request as new. No session, no history. Interactions work on the basis of the authentication mechanism such as OAuth, OpenID, JWT et cetra. It is the client’s responsibility to maintain user login stuff.

3. Cacheability

Clients and intermediaries can cache responses. Responses must, implicitly or explicitly, define themselves as either cacheable or non-cacheable to prevent clients from providing stale or inappropriate data in response to further requests. Well-managed caching partially or eliminates some client-server interactions, further improving scalability and performance.
Well-managed caching partially or completely eliminates some client-server interactions, further improving scalability and performance.

4. Layered system

A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. If a proxy or load balancer is placed between the client and server, it won’t affect their communications and there won’t be a need to update the client or server code.

5. Code on demand

This one is optional. Servers can temporarily extend or customize the functionality of a client by transferring executable code: for example, compiled components such as Java applets, or client-side scripts such as JavaScript.

6. Uniform interface

The uniform interface constraint is fundamental to the design of any RESTful system. It simplifies and decouples the architecture, which enables each part to evolve independently. The four constraints for this uniform interface are:

6.1 Resource identification in requests

Individual resources are identified in requests, for example using URIs in RESTful Web services. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server could send data from its database as HTML, XML or as JSON—none of which are the server’s internal representation.

6.2 Resource manipulation through representations

When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource’s state.

6.3 Self-descriptive messages

Each message includes enough information to describe how to process the message. For example, which parser to invoke can be specified by a media type.[3]

6.4 Hypermedia as the engine of application state (HATEOAS)

Having accessed an initial URI for the REST application—analogous to a human Web user accessing the home page of a website—a REST client should then be able to use server-provided links dynamically to discover all the available resources it needs. As access proceeds, the server responds with text that includes hyperlinks to other resources that are currently available. There is no need for the client to be hard-coded with information regarding the structure or dynamics of the application.


All the above constraints help you build a truly RESTful API, and you should follow them. Still, at times, you may find yourself violating one or two constraints. Do not worry; you are still making a RESTful API – but not “truly RESTful.”

Share on

Santosh Kumar
WRITTEN BY
Santosh Kumar
Fullstack Developer at Method Studios