How RESTful is your REST API

In real life, societies are backed up by powerful combat forces and weapons. If societies use these capabilities as they please, things would probably get out of order. Therefore, there are a lot of rules on when, why, how, and where to use them. We software people are living in the same world. Software is backed up by a huge arsenal of powerful technologies. We create rules and patterns on how to put them into optimal. The aftermath of misusing them ranges from unsatisfied customers to dead customers. Usually, when these patterns limit us, software people, we forge the pattern and the technology into a new one with new rules and patterns. HTTP is a powerful technology and REST is a pattern to ensure that it is used correctly for inter-process communication.

It starts with sending a request

A RESTful Service’s API gets interacted with using HTTP calls to a service one URL. These APIs are well-defined and their response pattern is usually anticipated. The API is usually exposed to operate on something by reading, creating, updating, or deleting it (CRUDing it). We, software people, are free to decide what is the scope of that something. However, we can lose our RESTfullness credibility if that scope either touches uncharted zones or goes rogue and operate.

It depends on the targeted resources

That’s the glorious cornerstone of REST. That’s the essence of it too which is mostly ignored. REST introduces the idea of resources. A RESTful request targets a specific resource. Either it is ordering a Turkish coffee or launching that Turkish coffee via a spaceship to the moon. A RESTful request is subjective to individual resources. The resource is identified per each request. For example, back to our Turkish coffee ordering system. I can call the coffee service to create a coffee order. Later, I can follow up to read the state of my coffee order by providing the id of that order. I can change my mind and cancel that order in favor of a latte (not). Moreover, I can be generous and send a request to change its state to launch it to the moon for aliens as a sign of civilization nearby on the planet earth. On either interaction, I interact with a resource.

You may outsmart the REST by providing a use case where it cannot be covered in a RESTful manner. That’s easy. However, in our case, for example, if I am interested in getting the bulk of my order history, then I am interacting with a resource that represents me as a customer. say customer identifier. If I want to act upon all the orders in the system, that’s a gray area. REST comes to the rescue by doing so. Getting such huge data in such a manner, need to be justified. REST may not be the answer to such use cases (event sourcing or streaming usually addresses such use cases). Of course, the reality is more nuanced. Each use case in this area should be examined carefully

REST is about operations too

REST provides us with 5 verbs to categorize the intent of the request:

1. GET: Read a resource data
2. POST: Create a new resource
3. PUT: Update a resource
4. PATCH: nitpicking resource update
5. DELETE: Delete the resource

Some of us may start turning off tables when compelled by these verbs. APIs are more simple when using POST for all requests that alter the data. For example, it requires exposing a hidden meaning to distinguish between altering an order or updating an order endpoint:

PUT https://localhost/coffeeservice/api/v1/orders/manageOrder
{ "servingDestination": "moon" }

vs

PATCH https://localhost/coffeeservice/api/v1/orders/manageOrder
{ "serveWithTurkishDelights": false }

Hence, a lot of us go rogue and explicitly address the request intent within the endpoint definition as follows:

https://localhost/coffeeservice/api/v1/orders/updateOrderDestination

and

https://localhost/coffeeservice/api/v1/orders/changeOrderSpecials

The latter is an anti-pattern. If it is how you update your resources, then your service is not RESTful. If it is up to me to judge, I would say, that’s a gray area. We software people are looking for clear definitions. However, we can clear it by providing the full language by exposing the intent of the payload.

Customers are demanding, they want to update a lot of things

That’s right, I want to update my coffee and I want to update my credit card information. That’s two different updates. verbs are a one-dimensional operation surface. However, together with the resources approach, that would be doable. The first resource is my order while the latter is my profile info.

API Disclosure (Hypermedia controls)

The proper term for that is hypermedia controls (as described in the book REST in practice — Hypermedia and Systems Architecture) which refers to the ugly acronym HATEOAS (Hypertext As the Engine of Application State). The goal is that upon the creation of a resource, the service responds with the possible options to apply to it. For example, when the coffee order is submitted, the service responds with endpoints to be called in order to cancel the order or replace it. This one can be beneficial only if tracked and examined. However, personally, I don’t think it is a fuzzy way to reflect on the supported functionality of a service.