What is REST?
The REST stands for REpresentational State Transfer.
Let's understand the meaning of each word in the REST acronym.
- State means data
- REpresentational means formats (such as XML, JSON, YAML, HTML, etc)
- Transfer means carrying data between consumer and provider using the HTTP protocol
Learn more about Rest at https://www.javaguides.net/p/rest-api-tutorial.html
1. Use Nouns for Resource Identification
The fundamental concept of a REST-based system is the resource. A resource is anything you want to expose to the outside world, through your application.
Example 1: Resources for Employee Management System:
- Employee
- Department
- Projects
- Task
- Address
Example 2: Resources for Student Management System:
- Student
- Teacher
- School
- Class
- Subject
A resource has an identifier, which is a URI that uniquely identifies that resource.
- GET - /users - Returns a list of users
- GET - users/100 - Returns a specific user
- POST - /users - Create a new user
- PUT - /users/ - Updates a specific user
- DELETE - /users/711 - Deletes a specific user
Bad Practice: Do not use verbs like:
/getAllUsers
/getUserById
/createNewUser
/updateUser
/deleteUser
2. Use Plural Nouns to Name a Resource
When you have to develop the resource in REST API, just go with plural nouns. Don't mix up singular and plural, use plural nouns to name a resource.3. Use Proper HTTP Headers for Serialization Formats
Content-Type defines the request format.
Accept defines a list of acceptable response formats.
Content-Type: application/json
Accept: application/json
4. Get Method and Query Parameters Should Not Alter the State
GET /users/711?activate or
GET /users/711/activate
5. Use Sub-Resources for Relations
GET /{resource}/{resource-id}/{sub-resource}
GET /{resource}/{resource-id}/{sub-resource}/{sub-resource-id}
POST /{resource}/{resource-id}/{sub-resource}
Use sub-resources child object cannot exist without its parent.
GET /cars/711/drivers/ Returns a list of drivers for car 711
GET /cars/711/drivers/4 Returns driver #4 for car 711
GET /tickets/12/messages
- Retrieves a list of messages for ticket #12GET /tickets/12/messages/5
- Retrieves message #5 for ticket #12POST /tickets/12/message
s - Creates a new message in ticket #12PUT /tickets/12/messages/5
- Updates message #5 for ticket #12PATCH /tickets/12/messages/5
- Partially updates message #5 for ticket #12DELETE /tickets/12/messages/5
- Deletes message #5 for ticket #12
6. Use Proper HTTP Methods (Verbs)
The URL is a sentence, where resources are nouns and HTTP methods are verbs.
- GET - retrieves a representation of the resource at the specified URI. The body of the response message contains the details of the requested resource.
- POST creates a new resource at the specified URI. The body of the request message provides the details of the new resource. Note that POST can also be used to trigger operations that don't actually create resources.
- PUT either creates or replaces the resource at the specified URI. The body of the request message specifies the resource to be created or updated.
- PATCH performs a partial update of a resource. The request body specifies the set of changes to apply to the resource.
- DELETE removes the resource at the specified URI.
7. HTTP Response Status Codes
- 200 OK: This code indicates that the request is successful and the response content is returned to the client as appropriate.
- 201 Created: This code indicates that the request is successful and a new resource is created.
- 400 Bad Request: This code indicates that the server failed to process the request because of the malformed syntax in the request. The client can try again after correcting the request.
- 401 Unauthorized: This code indicates that authentication is required for the resource. The client can try again with appropriate authentication.
- 403 Forbidden: This code indicates that the server is refusing to respond to the request even if the request is valid. The reason will be listed in the body content if the request is not a HEAD method.
- 404 Not Found: This code indicates that the requested resource is not found at the location specified in the request.
- 500 Internal Server Error: This code indicates a generic error message, and it tells that an unexpected error occurred on the server and that the request cannot be fulfilled.
8. Field Name Casing Convention
{ "firstName": "Ramesh", "lastName": "Fadatare", "id": 100, "userName": "Ramesh Fadatare", "email": "ramesh@gmail.com" }
9. Searching, Sorting, Filtering, and Pagination
- Sorting - In case, the client wants to get the sorted list of companies, the GET
/companies
endpoint should accept multiple sort params in the query. E.gGET /companies?sort=rank_asc
would sort the companies by their rank in ascending order.
- Filtering - For filtering the dataset, we can pass various options through query params. E.g
GET /companies?category=banking&location=india
would filter the companies list data with the company category of Banking and where the location is India.
- Searching - When searching for the company name in the companies list the API endpoint should be GET
/companies?search=Digital
.
- Pagination - When the dataset is too large, we divide the data set into smaller chunks, which helps in improving the performance and is easier to handle the response. Eg. GET
/companies?page=23
means get the list of companies on the 23rd page.
10. Restful API Versioning
API versioning is the practice of transparently managing changes to your API.
Here are the 4 ways of versioning a REST API.
1. Versioning through URI Path
2. Versioning through query parameters
3. Versioning through custom headers
4. Versioning through content negotiation
Read more about versioning REST APIs at https://www.javaguides.net/2021/04/rest-apis-versioning.html
Conclusion
Related REST API Articles
- Overview of REST
- What is Payload in REST API? // New
- REST API - HTTP Methods // Popular
- REST API - HTTP Status Codes // Popular
- Advantages of REST
- REST API - REST Architectural Constraints // Popular
- REST APIs Versioning
- REST API - REST Architectural Properties
- REST API - REST Architectural Elements
- Difference Between SOAP vs REST Web Services
- How to Identify REST Resources
- How to Design URL to REST Resource // Popular
- How to Assign HTTP methods to REST Resources
- How to Model JSON Representation Format // Popular
- What HTTP Status Code to Return
Free Spring Boot Tutorial | Full In-depth Course | Learn Spring Boot in 10 Hours
Watch this course on YouTube at Spring Boot Tutorial | Fee 10 Hours Full Course
Comments
Post a Comment