Rest API Design and Best Practices
The most important part while building any rest api is the api design i.e. URL. Here are the best practices while designing any rest api.
1. Segregate the apis into logical resources:
1. Segregate the apis into logical resources:
In Rest, the primary data representation entity is called resource. The key principle of rest involve separating your api into logical resources.
Example: For an e-commerce website, the possible resources can be orders, customers, vendors etc.
Example: For an e-commerce website, the possible resources can be orders, customers, vendors etc.
2. Resource names should be a noun (not verb):
RESTful URIs should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties which verbs do not have – similar to resources have attributes.
Example: /employees, /orders, /students, /posts etc. instead of /getEmployees, /createOrders
3. Use HTTP Methods to manipulate the resource:
Once you have your resources defined, you need to identify what actions apply to them and how those would map to your API. RESTful principles provide strategies to handle CRUD actions using HTTP methods mapped:
GET - To get resource
PUT - To create resource
POST - To update resource
DELETE - To delete resource
GET - To get resource
PUT - To create resource
POST - To update resource
DELETE - To delete resource
Example: Consider a use case of order resource in e-commerce, the possible actions can be getting all the orders, getting order by order id, creating order, update order, delete order etc. All these actions can be justified using HTTP methods as follows:
GET /orders - Get all the orders
GET /orders/2 - Get order of id 2
POST /orders - Create an order
PUT /orders/21 - Update order for id 21
DELETE /orders/12 - Delete order having id 12
4. Deal with relationships between the resources properly:
In certain scenarios, there can be relations between the resources like -orders associated with customer. RESTful principles provide useful guidance. The orders can be logically mapped to customer endpoint as follows:GET /customers/2/orders. - Get orders associated with customer having id 2
GET /customers/2/orders/12 - Get order with id 12 associated with customer with id 2
PUT /customers/15/orders/2 - Update order with id 2 for customer with id 15
5. Versioning the URL:
To manage this complexity, version your API. Versioning helps you iterate faster when the needed changes are identified. APIs only need to be up-versioned when a significant change is made. These changes include:
- A change in the format of the response data for one or more calls
- A change in the response type (i.e. changing an string to a integer)
- Removing any part of the API.
How to Version:
Using the URI is the most straightforward approach (and most commonly used as well).
Example: /v1/orders.
The version can be numeric “v[i]” syntax. You can also use dates or any other identifier that is flexible enough to change as the versions change.
Very nice article on rest api design and naming convention
ReplyDeleteNice one !!
ReplyDelete