How to do REST APIs?
Here is a post on reddit with a youtube video. It does a way better job of explaining how REST isn't done right than I can explain in this blog post.
You Give REST a Bad Name from r/javascript
What is a REST API really?
REST is same technology browsers use to talk to servers. You can easily find the code in every programming language to make an HTTP call. Building a REST client is easier compared to rolling out your own implementation. It's simple to understand and scalable since sessions and cookies are not needed. Just because of its a standard, the app knows what is expected by the server and what it can expect in return.
Its all about that Resource
The resource can be any real-world object. Let's say I have a coffee shop and I serve coffees and sandwiches. And I decide to make an app to take orders for them. So I will build a REST API to ask the server to
- Give details about a particular coffee or sandwich served.
- Save the orders, make changes in them or remove the entries.
Now let's say a customer orders both coffee and sandwich together. I can further think of "order" as an object, a real-world entity. That's exactly what a resource is.
According to me, identifying proper resources (coffee, order, sandwich etc.) is what makes a good REST API design.
The Resource Identifier
In REST, each coffee or sandwich will have an identifier. Likewise, each order will have an identifier. Whenever you are talking to a REST API, you are asking for a resource. If you are asking for a particular resource, you need to specify an id with your call to that resource.
"Give me the information about the coffee served in order number 32" looks like
/order/32/coffeeNow, if 3 coffees were served in order #32. REST API SHOULD give you information about all 3 coffees served. But, I need information only about the coffee #256. So, I will specify the id of coffee (256) served in that order (32).
/order/32/coffee/256Changing the order number (e.g. /order/64/coffee/128 ) should tell me about a coffee served in another order. With this example, we understand that objects can contain another object. The order contains coffee. An Order contains sandwiches. But coffee doesn't contain sandwich or vice-versa.
/coffee/32/sandwich/256So the REST API will give some error response if above is asked. If it's nice, it can tell you coffee doesn't contain sandwiches.
What happens behind the REST API?
Developers take the request for a resource and understand what the app wants to do with that resource. In the background, they do operations on the database or run some code. They handle all the errors. Perform checks on data sent in the request.
Stateless is REST's middle name.
So the developer has to keep everything in the database or somewhere else. REST won't keep anything with itself. It doesn't even remember the last resource you asked for. This frees the developer from managing sessions and it acts like the old apache server only to serve resources.
