Using HTTP Methods in RESTful APIs

Author:
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:

  1. Use GET method to retrieve an employee object by ID.

    • Example: /api/v1/employees/100

  2. Use GET method to retrieve all employees.

    • Example: /api/v1/employees

  3. Use POST method to create a new employee.

    • Example: /api/v1/employees

  4. Use PUT method to update an employee object by ID, passing the updated employee object as JSON.

    • Example: /api/v1/employees/100

  5. 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.

Comments

Post a Comment

Leave Comment