REST API - HTTP Methods

In this article, we will learn about the frequently used HTTP methods in building RESTful APIs.

REST APIs enable you to develop any kind of web application with all possible CRUD (create, retrieve, update, delete) operations. REST guidelines suggest using specific HTTP methods for different types of server requests.

Learn about RESTful APIs at Java Guides.

Let's explore HTTP methods and their roles in client-server communication over HTTP.

HTTP GET Method

Use GET requests to retrieve resource representation/information only – without modifying it in any way. GET requests do not change the state of the resource, making them safe methods. Additionally, GET APIs should be idempotent, meaning that making multiple identical requests must produce the same result every time until another API (POST or PUT) changes the state of the resource on the server.

If the address is successfully received (error-free), GET returns a JSON or XML representation 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 of GET request URIs:

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 GET - http://www.usermanagement/api/users/checkUsernameAvailability - Check if username is available to register
HTTP GET - 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 within a collection of resources.

Upon successful creation, an HTTP code 201 is returned, and the address of the created resource is transmitted in the ‘Location’ header.

Examples of POST request URIs:

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 a new comment for the post with id = postId
HTTP POST - http://www.domain/api/orders - Place a new order
HTTP POST - http://www.domain/api/products - Add a new product

When to Use GET and POST

Use GET:
- To retrieve data from the server.
- When the request has no side-effects.
- When you want to cache the response.
Examples:
- Retrieving user profile information.
- Fetching a list of products.
- Getting search results.
Use POST:
- To submit data to the server.
- When the request changes the state of the server.
- When you need to send large amounts of data.
Examples:
- Submitting a registration form.
- Posting a new blog entry.
- Uploading a file.

HTTP PUT Method

Use PUT APIs primarily to update existing resources. If the resource does not exist, the API may decide to create a new resource or not. If a new resource is created by the PUT API, the origin server must inform the user agent via the HTTP response code 201 (Created). If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes should be sent to indicate the successful completion of the request.

Examples of PUT request URIs:

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 the post with id = postId
HTTP PUT - http://www.domain/api/orders/{orderId} - Update order details
HTTP PUT - http://www.domain/api/products/{productId} - Update product information

The difference between 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 to 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.

Examples of DELETE request URIs:

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 the post with id = postId
DELETE - http://www.domain/api/orders/{orderId} - Cancel order
DELETE - http://www.domain/api/products/{productId} - Remove product

HTTP PATCH Method

HTTP PATCH requests are used to make partial updates on a resource. Unlike PUT requests, which also modify a resource entity, PATCH is the correct choice for partially updating an existing resource, while PUT should only be used if you’re replacing a resource in its entirety.

Example of a PATCH request:

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 need to perform a partial update, they can use PATCH.

For instance, when updating a single field of a resource, sending the complete resource representation might be cumbersome and use a lot of unnecessary bandwidth. In such cases, the semantics of PATCH make more sense.

Another important aspect is idempotence; PUT is idempotent, while PATCH can be but isn't required to be. Depending on the semantics of the operation, you can choose one or the other based on this characteristic.

HTTP OPTIONS Method

The HTTP OPTIONS method is used to describe the communication options for the target resource. It can be used to check which HTTP methods a server supports.

Example of an OPTIONS request:

HTTP OPTIONS - http://www.domain/api/users - Check allowed methods for users resource

HTTP HEAD Method

The HTTP HEAD method is identical to GET except that the server must not return a message body in the response. It is useful for retrieving meta-information written in response headers without transferring the entire content.

Example of a HEAD request:

HTTP HEAD - http://www.domain/api/users/{username} - Retrieve meta-information about a user without the response body

HTTP TRACE Method

The HTTP TRACE method performs a message loop-back test along the path to the target resource. It is used for diagnostic purposes.

Example of a TRACE request:

HTTP TRACE - http://www.domain/api/resource - Perform a loop-back test to the resource

Summary of HTTP Methods

Here is a summary of REST APIs for a User Management Application, including five REST APIs for the User resource:

API List

Conclusion

In this article, we have learned about commonly used HTTP methods in RESTful APIs with examples.

Learn how to develop REST APIs using the Jersey framework at Java Guides.

Learn how to develop REST APIs using JAX RS with the RESTEasy framework at Java Guides RESTEasy Tutorial.

Java Guides

Search This Blog