Using HTTP Methods in RESTful APIs

🎓 Top 15 Udemy Courses (80-90% Discount): My Udemy Courses - Ramesh Fadatare — All my Udemy courses are real-time and project oriented courses.

▶️ Subscribe to My YouTube Channel (178K+ subscribers): Java Guides on YouTube

▶️ For AI, ChatGPT, Web, Tech, and Generative AI, subscribe to another channel: Ramesh Fadatare on YouTube

In this post, we will explore the usage of HTTP methods and how to assign them to RESTful resources. This is the third step in designing a RESTful API. Previously, we covered:

HTTP Methods Overview

We will look at the HTTP methods GET, POST, PUT, DELETE, and PATCH one by one and conclude with a case study to illustrate their usage.

GET

The HTTP GET method is used to read or retrieve a representation of a resource. In a successful request, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In error cases, it commonly returns 404 (NOT FOUND) or 400 (BAD REQUEST).

According to the HTTP specification, GET (along with HEAD) requests are used solely to read data and should not change it. This makes GET a safe method, meaning it can be called without risking data modification or corruption. Additionally, GET is idempotent, meaning multiple identical requests will have the same effect as a single request.

Examples:

GET http://www.example.com/customers/12345
GET http://www.example.com/customers/12345/orders
GET http://www.example.com/buckets/sample

POST

The POST method is used to create new resources. When creating a subordinate resource, POST to the parent resource, and the service will handle associating the new resource with the parent and assigning an ID.

On successful creation, return HTTP status 201 with a Location header containing a link to the newly created resource.

POST is neither safe nor idempotent. Making two identical POST requests will likely result in two resources containing the same information.

Examples:

POST http://www.example.com/customers
POST http://www.example.com/customers/12345/orders

PUT

PUT is typically used to update a resource, sending the updated representation to a known resource URI. If the client chooses the resource ID and the resource does not exist, PUT can also create one.

On a successful update, return 200 (or 204 if no content is returned). If using PUT for creation, return HTTP status 201. It is not necessary to return a link via a Location header since the client already set the resource ID.

Examples:

PUT http://www.example.com/customers/12345
PUT http://www.example.com/customers/12345/orders/98765
PUT http://www.example.com/buckets/secret_stuff

DELETE

DELETE is used to remove a resource identified by a URI. On successful deletion, return HTTP status 200 (OK) with a response body or 204 (NO CONTENT) with no response body.

Examples:

DELETE http://www.example.com/customers/12345
DELETE http://www.example.com/customers/12345/orders
DELETE http://www.example.com/bucket/sample

PATCH

PATCH is used to modify a resource. Unlike PUT, which sends a complete updated resource, PATCH sends only the changes to the resource.

The PATCH body should contain a set of instructions on how to modify the resource, often in a format like JSON Patch or XML Patch.

Examples:

PATCH http://www.example.com/customers/12345
PATCH http://www.example.com/customers/12345/orders/98765
PATCH http://www.example.com/buckets/secret_stuff

Case Study: Employee Management System (EMS)

In this case study, we'll examine the Employee Management System (EMS) application. We will identify and perform various resource operations:

Use GET method to retrieve an employee object by ID.
- Example: /api/v1/employees/100
Use GET method to retrieve all employees.
- Example: /api/v1/employees
Use POST method to create a new employee.
- Example: /api/v1/employees
Use PUT method to update an employee object by ID, passing the updated employee object as JSON.
- Example: /api/v1/employees/100
Use PATCH method to partially update an employee object.
- Example: /api/v1/employees/100

Conclusion

In this post, we learned how to assign HTTP methods to REST resources. In the next step, we will learn how to format resource representations like JSON and XML.

My Top and Bestseller Udemy Courses. The sale is going on with a 70 - 80% discount. The discount coupon has been added to each course below:

Spring Boot + RabbitMQ Course - The Practical Guide

Java Guides

Search This Blog