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": "[email protected]" }
  ]
  

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:

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.

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