How to create more expressive APIs
REST is good but, have you tried intent based?
As engineers, we tend to use the standards. They are battle tested.
But have you asked yourself if there is a nicer approach to integrate/create APIs?
What is REST?
REST (Representational State Transfer) is a software architectural style that defines a set of constraints to be used for creating web services.
A REST API (Application Programming Interface) is a set of rules that defines how two software systems can interact over a network. It is a way for two computers to communicate with each other over the internet, allowing them to exchange information and trigger actions.
We all know that , right? But REST, to be REST, we need to follow the HTTP verbs:
- Create: To create a new resource
- Read: To retrieve a resource
- Update: To update an existing resource
- Delete: To delete a resource
These operations are implemented using the HTTP methods: POST, GET, PUT, and DELETE, respectively. We tend to use route parameters as well to interact with certain accuracy.
The problem with REST
Lets take a products management system as an example.
The system might include functionality for creating and updating product information, managing inventory levels, and processing orders.
- GET /products: This endpoint returns a list of all products in the system, along with their details such as name, price, and quantity in stock.
- POST /products: This endpoint creates a new product in the system. The request body might include information such as the product name, price, and quantity.
- GET /products/{id}: This endpoint returns the details of a specific product, identified by its ID.
- PUT /products/{id}: This endpoint updates the details of a specific product, identified by its ID. The request body might include information such as the updated product name, price, and quantity.
- DELETE /products/{id}: This endpoint deletes a specific product, identified by its ID.
It seems pretty straightforward. Because it is.
However, overtime, it becomes harder to maintain. Applications always grows and we need to be able to give it the space to grow too.
Imagine if this application now, allows the creation of storage facilities where these products are stored. Now you have to copy/paste all routes, but change the products prefix.
Also, you can end up with endpoints like this:
- POST /products/{facilityId}
- GET /products/{facilityId}/{id}
Your application will become a hostage to this approach. And you may not realize it yet, but it costs time and energy to refactor.
Because now, your whole application is coupled into this design.
Intent Based to the rescue
Intent Based APIs allows developers to build applications that can understand the intent behind a user’s words, rather than just processing specific commands or keywords.
This approach is more human friendly, and helps not only the integration with your API but its development as well.
Lets go back to our previous example and change our REST API to behave as Intent Based:
- GET /products/get-all
- POST /products/create-one
- GET /products/get-one?{id}
- PUT /products/update-one
- DELETE /products/delete-one?{id}
With this more verbose approach, we can better understand what each route do without paying too much attention to its request method.
This also helps to extend functionality. If we want to be able to interact with more products, we do as follows:
- POST /products/create-many
- GET /products/get-many?{ids}
- PUT /products/update-many
- DELETE /products/delete-many?{id}
Well, you may argue that that’s the same as in a REST API. Well, kinda.
Now your application is expressive. It isn’t coupled to your routes anymore. Your controllers don’t need to know the amount of parameters it gets or the type of the request. You just infers from the route name which parameters and which entities your controller will interact.
And it saves you time. As developers, we tend to leave things for a later moment. But if you start with intent based, your need to refactor routes in the future will reduce.
