In this article, we will learn the frequently used HTTP methods in building RESTful APIs.
REST APIs enable you to develop any kind of web application having all possible CRUD (create, retrieve, update, delete) operations. REST guidelines suggest using a specific HTTP method on a particular type of call made to the server.
Learn about RESTful APIs at https://www.javaguides.net/p/restful-tutorial.html
Let's learn about HTTP methods and their role in client-server communication over HTTP.
HTTP GET Method
Use GET requests to retrieve resource representation/information only – and not to modify it in any way. As GET requests do not change the state of the resource, these are said to be safe methods. Additionally, GET APIs should be idempotent, which means that making multiple identical requests must produce the same result every time until another API (POST or PUT) has changed the state of the resource on the server.
If the address is successfully received (error-free), GET returns a JSON or XML representation in combination with the HTTP status code 200 (OK). In case of an error, the code 404 (NOT FOUND) or 400 (BAD REQUEST) is usually returned.
Examples for GET request URI's:
HTTP GET - http://www.usermanagement/api/users/me - Get logged in user profile
HTTP GET - http://www.usermanagement/api/users/{username}/profile - Get user profile by username
HTTP GET - http://www.usermanagement/api/users/{username}/posts - Get posts created by user
HTTP GET - http://www.usermanagement/api/users/{username}/albums - Get albums created by user
http://www.usermanagement/api/users/checkUsernameAvailability - Check if username is available to register
http://www.usermanagement/api/users/checkEmailAvailability - Check if email is available to register
HTTP POST Method
The HTTP POST request is most commonly used to create new resources. When talking strictly in terms of REST, POST methods are used to create a new resource into the collection of resources.
Upon successful creation, an HTTP code 201 is returned, and the address of the created resource is also transmitted in the ‘Location’ header.
Here are some examples for HTTP POST requests:
HTTP POST - http://www.domain/api/users - Create User
HTTP POST - http://www.domain/api/posts - Create Post
HTTP POST - http://www.domain/api/posts/{postId}/comments - Create new comment for post with id = postId
HTTP PUT Method
Use PUT APIs primarily to update existing resource (if the resource does not exist, then API may decide to create a new resource or not). If a new resource has been created by the PUT API, the origin server MUST inform the user agent via the HTTP response code 201 (Created) response and if an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.
Here are some examples for HTTP Put requests:
HTTP PUT - http://www.domain/api/users/{username} - Update user
HTTP PUT - http://www.domain/api/posts/{id} - Update post by id
HTTP PUT - http://www.domain/api/posts/{postId}/comments/{id} - Update comment by id if it belongs to post with id = postId
The difference between the POST and PUT APIs can be observed in request URIs. POST requests are made on resource collections, whereas PUT requests are made on a single resource.
HTTP DELETE Method
Use DELETE APIs to delete resources (identified by the Request-URI).
A successful response of DELETE requests SHOULD be HTTP response code 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has been queued, or 204 (No Content) if the action has been performed but the response does not include an entity.
Here are some examples for HTTP Delete requests:
DELETE http://www.domain/api/users/{username} - Delete user
DELETE http://www.domain/api/posts/{id} - Delete post
DELETE http://www.domain/api/posts/{postId}/comments/{id} - Delete comment by id if it belongs to post with id = postId
HTTP PATCH Method
HTTP PATCH requests are to make partial updates on a resource. If you see PUT requests also modify a resource entity, so to make more clear – the PATCH method is the correct choice for partially updating an existing resource, and PUT should only be used if you’re replacing a resource in its entirety.
Example:
A sample patch request to update the email will be like this:
HTTP PATCH /users/1
[
{ “op”: “replace”, “path”: “/email”, “value”: “new.email@example.org” }
]
When to Use HTTP PUT and When HTTP PATCH?
When a client needs to replace an existing Resource entirely, they can use PUT. When they're doing a partial update, they can use HTTP PATCH.
For instance, when updating a single field of the Resource, sending the complete Resource representation might be cumbersome and utilizes a lot of unnecessary bandwidth. In such cases, the semantics of PATCH make a lot more sense.
Another important aspect to consider here is idempotence; PUT is idempotent; PATCH can be, but isn't required to. And, so – depending on the semantics of the operation we're implementing, we can also choose one or the other based on this characteristic.
Summary of HTTP Methods
Conclusion
In this article, we have learned about commonly used HTTP methods in RESTful API with examples.
Learn how to develop REST API's using the Jersey framework at https://www.javaguides.net/p/restful-tutorial.html
Learn how to develop REST API's using JAX RS with RESTEasy framework at https://www.javaguides.net/2020/01/resteasy-crud-example-tutorial.html
Related REST Articles
- Overview of REST
- REST API - HTTP Methods
- REST API - HTTP Status Codes
- Advantages of REST
- REST API - REST Architectural Constraints
- 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
- How to Assign HTTP methods to REST Resources
- How to Model JSON Representation Format
- 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