REST API - HTTP Methods

Author:

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

REST API's for User Management Application - Following five REST APIs for User resource:

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

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