REST API HTTP Methods

HTTP methods are the verbs of REST. They tell the server what action to perform on a resource. Each method has a specific, agreed-upon meaning. Using them correctly is what separates a well-designed API from a confusing one.

The Five Core HTTP Methods

┌────────────┬──────────────────────┬───────────────┬───────────────┐
│  Method    │  Action              │  Has Body?    │  Safe?        │
├────────────┼──────────────────────┼───────────────┼───────────────┤
│  GET       │  Read a resource     │  No           │  Yes          │
│  POST      │  Create a resource   │  Yes          │  No           │
│  PUT       │  Replace a resource  │  Yes          │  No           │
│  PATCH     │  Update part of it   │  Yes          │  No           │
│  DELETE    │  Remove a resource   │  No           │  No           │
└────────────┴──────────────────────┴───────────────┴───────────────┘

"Safe" means the method does not change any data on the server.

GET – Read Data

GET retrieves data. It never changes anything on the server. Think of it as asking a question.

GET /products           → Get all products
GET /products/42        → Get product #42
GET /users/5/orders     → Get all orders for user #5

Response example for GET /products/42:
HTTP 200 OK
{
  "id": 42,
  "name": "Wireless Keyboard",
  "price": 1499,
  "stock": 120
}

GET requests have no request body. All input comes from the URL and query parameters (like /products?category=electronics).

POST – Create Data

POST creates a new resource. The client sends data in the request body. The server creates the resource and typically returns the newly created item with its assigned ID.

POST /products
Request body:
{
  "name": "USB-C Hub",
  "price": 999,
  "stock": 50
}

Response: HTTP 201 Created
{
  "id": 87,
  "name": "USB-C Hub",
  "price": 999,
  "stock": 50
}

The server assigns the ID, not the client. The response code for a successful POST is 201 Created, not 200.

PUT – Replace Data

PUT replaces an entire resource. You send the full object with all fields. The server overwrites the existing resource completely with what you send.

PUT /products/87
Request body (all fields required):
{
  "name": "USB-C Hub Pro",
  "price": 1199,
  "stock": 45
}

Result: Product #87 is completely replaced with this new data.
        Any field you omit gets overwritten with null or a default.

Use PUT when you want to fully replace a resource and you always send all fields.

PATCH – Partial Update

PATCH updates only the fields you specify. It does not touch any other fields.

Existing product #87:
{
  "id": 87,
  "name": "USB-C Hub Pro",
  "price": 1199,
  "stock": 45
}

PATCH /products/87
Request body (only the fields to change):
{
  "price": 1099
}

Result:
{
  "id": 87,
  "name": "USB-C Hub Pro",    ← unchanged
  "price": 1099,              ← updated
  "stock": 45                 ← unchanged
}

PATCH is more efficient than PUT when you need to update just one or two fields of a large resource.

PUT vs PATCH: A Clear Comparison

┌────────────────────────────────────────────────────────────────┐
│  You have a user profile with 10 fields.                       │
│  You want to update only the phone number.                     │
│                                                                │
│  PUT:   Send all 10 fields. 9 are unchanged.  (wasteful)       │
│  PATCH: Send only phone number.               (efficient)      │
└────────────────────────────────────────────────────────────────┘

DELETE – Remove Data

DELETE removes a resource. A successful deletion returns 204 No Content (the resource is gone, so there is nothing to return in the body).

DELETE /products/87

Response: HTTP 204 No Content
(no body — the product no longer exists)

If you try to DELETE a resource that does not exist, return 404 Not Found.

Idempotency: A Critical Concept

An operation is idempotent if calling it multiple times produces the same result as calling it once. This matters for reliability — what happens if a network hiccup causes the client to retry a request?

┌────────────┬────────────────────────────────────────────────────┐
│  Method    │  Idempotent?                                       │
├────────────┼────────────────────────────────────────────────────┤
│  GET       │  Yes – reading the same data twice returns the     │
│            │  same result                                       │
│  PUT       │  Yes – replacing a resource twice with the same    │
│            │  data produces the same state                      │
│  PATCH     │  Usually yes (depends on implementation)           │
│  DELETE    │  Yes – deleting something twice: first succeeds,   │
│            │  second gets 404, but the final state is the same  │
│  POST      │  No – posting twice creates two separate records   │
└────────────┴────────────────────────────────────────────────────┘

Mapping Methods to a Books API

Action                         │  Method  │  URL
───────────────────────────────┼──────────┼──────────────────
Get all books                  │  GET     │  /books
Get a specific book            │  GET     │  /books/5
Add a new book                 │  POST    │  /books
Replace a book's data          │  PUT     │  /books/5
Update only the book's title   │  PATCH   │  /books/5
Delete a book                  │  DELETE  │  /books/5

Key Points

• GET reads, POST creates, PUT replaces, PATCH partially updates, DELETE removes
• GET and DELETE have no request body
• POST returns 201 Created; DELETE returns 204 No Content on success
• GET, PUT, and DELETE are idempotent; POST is not
• Use PATCH instead of PUT when updating only a few fields