1. Statelessness
In a very simple word, each request should be sufficient in itself to be understood by the server. In other words, the action to a request should not depend on information provided by any prior request. Each request should be an atomic operation.
But why statelessness is a constraint?
- Because It enables us to scale as there is no need to be any affinity between a client and specific servers. Any server can handle any request
- It increases the reliability as the failure of one independent request has less overhead in recovery
- Makes the implementation simple as server doesn’t need to maintain resources across requests.
Does statelessness has disadvantage?
- It might decreases the network performance as similar data may have to be sent in the multiple requests because data can’t be stored in the server.
2. APIs Designed Around Business Entity
APIs should revolve around the business entity. For example, consider a e-commerce application. At the very basic of it, most of the e-commerce application has three entity: user, order and payment. Restful APIs comprises of HTTP methods (or verb) like GET, POST, PUT and DELETE.
Your restful API name should be a noun (as it is a name) so that together with the HTTP verbs (or method), the API signatures make a complete statement. That also communicates the client the usage of the API in a nut shell.
I went for dinner and found manager saying this to his waiter.
Hey! get the order of customer number 6.
Wait! Let’s do magic as we do with computers and translate this statement to a restful API signature.
GET /customers/{customerId}/orders
How about I shouting my order? 1 pasta and 1 pizza, please. And the waiter says, OK, your order is 10th.
POST /orders
{
"pasta" : 1,
"pizza" : 1,
"customerId" : 6
}
Response:
Status : 201 Created
{
"orderId" : 10
}
Pretty cool.
And then my friend tells me that he is starving. May be we could order 2 pizzas.
Hey waiter! Can we please update our order? We want two pizzas, so please put the quantity as 2.
PUT /orders
{
"orderId" : 10,
"pizza" : 2
}
But that was a bad place to eat? They made us wait two hours and ah! no food still. We call the order and tell him to forget about our order.
DELETE /orders/10
I say pretty cool translation of English.
Its about perspective.
What if we want to fetch details based on several query parameters? So much so that the query params become unreadable. Or even worse? URL reaches the max limit of the size.
Should we encode the URL? At least this SO discussion says so.
Or should we use POST? This SO thread advocates that.
3. HTTP Status Code
Media Type
This allows the API client to interpret the data in the payload. Correct Media Type constraints the structure of the data and what that data means.
A client request can include an Accept header that contains a list of media types the client will accept from the server in the response message.
Status Codes
415 : If the server doesn’t support the media type.
406 : If the server cannot match any of the media types accepted by the client.
200 : If resource is found by GET (POST too, if POST is not v)
404 : If resource is not found by GET
201 : If resource is created by POST
204 : If POST has nothing to return
400 : If client sends bad request to create through POST
409 : If PUT is unable to update and finds conflict
204 : If DELETE does successful operation
4. Versioning of APIs
Change in business requirement over time changes the structure of resources and their relation. Updating a web API to handle requirements is a simple process, we should consider the effects that the changes will have on the existing client.
There are three popular ways to achieve versioning :
-
URI versioning
POST /orders and POST v1/orders
-
Header versioning
headers version-header : 2
-
Query string versioning
GET /orders and GET /orders?version=2
Fun Fact :The term representational state transfer was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation at UC Irvine.
Further Reading:
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
https://evertpot.com/rest-is-in-the-eye-of-the-beholder/
https://martinfowler.com/articles/richardsonMaturityModel.html
https://swagger.io/blog/api-design/api-design-best-practices/
https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_3
If you liked this article and would like one such blog to land in your inbox every week, consider subscribing to our newsletter: https://skillcaptain.substack.com