Skip to content
Hironobu Iga

Classifying HTTP methods in an API

Sorting GET, POST, PUT, PATCH, DELETE and HEAD by what they do to a resource — and pinning down the difference between the three that are easy to confuse.

Published

This article is also published elsewhere. https://iganin.hatenablog.com/entry/2020/08/10/210711

Originally written in Japanese. This is a translation of the same piece.

An API request carries an HTTP method alongside its URI. GET and DELETE explain themselves, but POST, PUT and PATCH — and the differences between them — take me a moment to recall every time, so this is a note to stop paying that cost repeatedly.

Classification

  • GET
    • Read a resource
  • POST
    • Create a new resource
  • PUT
    • Replace a resource that already exists
  • PATCH
    • Amend a resource that already exists
  • DELETE
    • Delete a resource that already exists
  • HEAD
    • Check metadata

Method by method

The examples below all work from https://sample.com/api/v1/items/.

GET

Reads a resource. Usually either https://sample.com/api/v1/items/${item_id}, narrowing to exactly one resource by id, or https://sample.com/api/v1/items for a list.

GET only reads: it does not amend or delete the resource itself. (State changes that follow from the read, such as marking something as seen, look like an exception to this.)

POST

Creates a new resource. You request https://sample.com/api/v1/items and the corresponding resource is created. As described in RFC 7231, the id assigned during creation is often returned — so if a POST to https://sample.com/api/v1/items creates an item and it is assigned the id 12345, the response returns 12345.

If one or more resources has been created on the origin server as a result of successfully processing a POST request, the origin server SHOULD send a 201 (Created) response containing a Location header field that provides an identifier for the primary resource created and a representation that describes the status of the request while referring to the new resource(s).

PUT

Updates the information at the given URI. It does not update it partially — it replaces it with the values contained in the new request. Given the resource below, a request to https://sample.com/api/v1/items/12345 with name = “sample” and category = “sample” overwrites the resource identified by 12345 and returns 200 (OK) or 204 (No Content). If no resource exists at that URI, a new one is created and 201 (Created) is returned.

{
  "id": "12345",
  "name": "hoge",
  "category": "fuga"
}

PATCH

Partially updates the information at the given URI. Where PUT replaced the resource at the URI with a new one, this method overwrites part of it. Taking the resource used for PUT above, a request to https://sample.com/api/v1/items/12345 with name = “sample” amends it as follows.

{
  "id": "12345",
  "name": "sample",
  "category": "fuga"
}

DELETE

Deletes the resource at the given URI. The response status codes are defined as follows (from RFC 7231).

202 (Accepted) if the action will likely succeed but has not yet been enacted
204 (No Content) if the action has been enacted and no further information is to be supplied
200 (OK) if the action has been enacted and the response message includes a representation describing the status

Nearly identical to a GET request, but only the headers are returned. Payload header fields may also be omitted from what comes back.

Summary

A short pass over what each HTTP method is for. POST is used far more variously in practice, but this organises the methods by how they treat a single resource. The RFCs turned out to be the most useful reference while looking into this, and are worth reading directly.

References

Read next