Act # 29 HTTP Methods

HTTP methods are used to define the actions that an API client wants to perform on a resource. Each method corresponds to a specific operation like creating, reading, updating, or deleting a resource, and every REST API request must include an HTTP method to specify the desired action.

In this overview, we'll explain the relationship between HTTP methods and REST APIs and highlight the most commonly used HTTP methods, as well as discuss which methods are safe and idempotent.

Common HTTP Methods

HTTP methods allow API clients to perform CRUD (Create, Read, Update, and Delete) operations on resources in a standardized and predictable manner. The most commonly used HTTP methods are:

• GET
  The GET method is used to retrieve data from a server. Clients can use GET to access all resources of a given type or a specific resource. For example, a GET request to the /products endpoint would return a list of all products, while a GET request to /products/123 would return the specific product with an ID of 123. GET requests typically do not include a request body because they are only for retrieving data, not modifying it.

• POST
  The POST method is used to create new resources. For instance, a store manager might send a POST request to the /products endpoint to add a new product to the database. POST requests often include a request body, where the client specifies the attributes of the resource to be created. An example POST request to add a product might look like this:

    jsonCopy code{
      "name": "Sneakers",
      "color": "blue",
      "price": 59.95,
      "currency": "USD"
    }
  

• PUT
  The PUT method is used to replace an existing resource with an updated version. PUT replaces the entire resource at a specific URL with the data provided in the request body. Any properties not included in the request body will be deleted, and new properties will be added.

• PATCH
  The PATCH method is used to update specific properties of an existing resource. Unlike PUT, which replaces the entire resource, PATCH only modifies the specified properties. For example, if you want to update only the price of a product while leaving other fields unchanged, you can use PATCH. This method is more flexible and efficient than PUT for partial updates.

• DELETE
  The DELETE method is used to remove a resource. When a client sends a DELETE request, it asks the server to delete the resource located at the specified URL. For example, a DELETE request to /products/123 would permanently remove the product with ID 123 from the database. Some APIs may implement authorization to ensure that only clients with the correct permissions can delete resources.

Safe HTTP Methods

Safe methods are used for read-only operations, meaning they do not modify the resources in any way. The GET method is the most commonly used safe method, and the HEAD method, which retrieves only the headers of a resource, is also considered safe.

Idempotent HTTP Methods

An HTTP method is considered idempotent if executing it multiple times results in the same outcome. All safe methods (GET and HEAD) are idempotent, as are the PUT and DELETE methods. For example:

• A PUT request will update a resource with the provided data, and repeating the request will always produce the same result.

• A DELETE request will remove a resource, and running it multiple times will have no additional effect once the resource is gone.

On the other hand, POST is not idempotent because calling it multiple times can create multiple instances of a resource. PATCH can be idempotent, but it is not guaranteed. For example, a PATCH request might increment a field each time it is called, resulting in different outcomes on repeated executions.