1. Statelessness
In simple words, each request should be sufficient in itself to be understood by the server. The action to a request should not depend on the information provided by any prior request. Each request should be an atomic operation.
But why statelessness is a constraint?
It enables us to scale as there is no need for any affinity between a client and a specific server. Any server can handle any request.
It increases reliability as the failure of one independent request has less overhead in recovery.
It makes the implementation simple as the server doesn’t need to maintain resources across requests.
Does statelessness have a disadvantage?
It might decrease the network performance as similar data may have to be sent in multiple requests, since data can’t be stored in the server.
2. APIs Designed Around Business Entity
APIs should revolve around the business entity.
For example, consider an e-commerce application. At the very core, most e-commerce applications have three entities: user, order and payment. Restful APIs comprise HTTP methods (or verbs) 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. It also gives the client an overview of the API's usage.
I went for dinner and found the manager saying this to his waiter.
Hey! Get the order of customer number 6.
Let’s translate this statement to a restful API signature.
GET /customers/{customerId}/orders
If I place an order - 1 pasta and 1 pizza, please. And the waiter says, okay, your order number is 10.
POST /orders
{
"pasta" : 1,
"pizza" : 1,
"customerId" : 6
}
Response:
Status : 201 Created
{
"orderId" : 10
}
And then my friend tells me that he is starving. Maybe we should order 2 pizzas instead of 1.
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 it was not a great place to eat. They made us wait for 90 minutes and still no food. We call the waiter and ask him to forget about our order.
DELETE /orders/10
A pretty cool translation of English.
It’s 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? What if 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 for that.
3. HTTP Status Code
Media Type
This allows the API client to interpret the data in the payload. Correct Media Type puts a constraint on 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 the resource is found
404: If the resource is not found by GET
201: If the resource is created by POST
204: If POST has nothing to return
400: If the client sends a bad request to create through POST
409: If PUT is unable to update and finds a conflict
204: If DELETE does a successful operation
4. Versioning of APIs
Changes in business requirements over time change the structure of the resources and their relation. Updating a web API to handle the 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 (REST) was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation at UC Irvine.
Further Reading:
Best Practices in API Design -
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
REST is in the eye of the beholder -
Richardson Maturity Model -https://martinfowler.com/articles/richardsonMaturityModel.html
Best Practices in API Design -
https://swagger.io/blog/api-design/api-design-best-practices/
Best Practices for Designing a Pragmatic RESTful API -
https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
Representational State Transfer (REST) -
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_3