Best practices to design REST API calls
RESTful web services is becoming much popular because of the layered architecture, client-server model, and it allows to transfer data not only xml, JSON, YML also.
Need to follow best practices to design good RESTful web service application.
#1 Use nouns instead of verbs in the URI’s.
Always prefer to use the Nouns instead of verbs in the path, since the URL http method already contains the verb, this represents the purpose of the operation.
These http methods represents the CRUD operations. GET method retrieves data from system, POST method creates data, PUT method updates the data and DELETE method removes the data.
The forward slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources.
#WrongPOST : /orders/createOrder
GET: /orders/getOrder/{orderId}
PUT: /orders/updateOrder
DELETE: /orders/deleteOrder
#Correct
POST : /orders
GET: /orders/{orderId}
PUT: /orders/{orderId}
DELETE: /orders/{orderId}#2 Always prefer to accept and respond with JSON
Always prefer to transfer data in the form of JSON format, because most of the softwares including javascript are supporting JSON formats.
Accept header is used by HTTP client, it informs server which format of data client expecting. Content-Type is used by both client and server, which format of data client send in request and which format of data send response from server.
#3 Always prefer resources with plural nouns
Always prefer to write URI’s with plural form, so that it helps to users to manage resources singular or plural. we have to plural form across all HTTP methods GET, POST, PUT and DELETE.
#4 Handle errors gracefully and return standard error codes
Handle errors gracefully with suitable HTTP error codes to avoid the confusing. From Server side we need to inform the client with suitable error code whether the request failed or processed successfully.
1xx — Informational -- Server acknowledges a request
2xx — success -- Server completed the request successfully.
3xx — redirect -- Client need to redirect the action to complete the request.
4xx — Client errors -- Client sent an invalid input.
5xx — server errors -- Server failed to process the input request.#5 Design API to perform filter, sort, and pagination
The databases behind a REST API can get very large. Sometimes, there’s so much data that it shouldn’t be returned all at once because it’s way too slow or will bring down our systems. Therefore, we need ways to filter items.
Filtering:
GET /orders?userId=John
GET /orders?Order_date=2020-12-12Sorting:
GET /orders?sort=order_date:ascPaging:
GET /orders?limit=10
#6 Nesting resources which are parent child relationship
Nested resources should be appended with parent resource. nesting too many resources causes confusion, always limit to 1. For every order we provide the feedback, it will more understandable if we desing URI with order and orderId.
GET: /order/{orderId}/feedback
#7 Versioning our APIs is recommended
In real time applications APIs will be using by variety of applications like mobile applications, web applications etc. Always recommended to use versioning in APIs. So that if the mobile application uses old version it will use relevant API. If any unforeseen issues happen client can use old API’s.
#8 Handle Training slashes carefully
Use trailing slash / to contain the hierarchical relationship between the resources. Always inform clients with correct URI else redirect it accordingly.
Note: No need to add forward slash at the end of the URI.
#9 underscores should not be used
Use hyphens for readability instead of under scores.
#10 Lowercase letters should be preferred in URI paths
Always prefer to use lower case letters in the URI to avoid the confusion.
