HTTP Verbs

HTTP methods (verbs) define what action to perform on a resource.

Key Concepts

Before diving into the methods, understand these two important properties:

Idempotent: Making the same request multiple times produces the same result. For example, deleting a resource twice has the same effect as deleting it once (the resource is gone). This is crucial for reliability: if a network fails mid-request, the client can safely retry.

Safe: The request doesn’t modify server state. Safe methods are read-only and can be cached, prefetched, or retried without side effects.

---

Method Summary

Method	Purpose	Idempotent	Safe	Request Body
GET	Retrieve resource(s)	Yes	Yes	No
POST	Create new resource	No	No	Yes
PUT	Replace entire resource	Yes	No	Yes
PATCH	Partial update	Yes*	No	Yes
DELETE	Remove resource	Yes	No	No

*PATCH is idempotent when implemented correctly (same patch = same result)

---

GET - Retrieve Resources

Retrieves one or more resources without modifying server state.

# Get collection
GET /api/books
Accept: application/json

# Get single resource
GET /api/books/123
Accept: application/json

Rules:

• Must be idempotent (same request = same response)
• Must be safe (no side effects)
• Never modify server state

---

POST - Create Resource

Creates a new resource within a collection. The server typically generates the resource ID.

POST /api/books
Content-Type: application/json

{
  "title": "The Great Gatsby",
  "author": "F. Scott Fitzgerald",
  "year": 1925
}

Response:

201 Created
Location: /api/books/456

{
  "id": 456,
  "title": "The Great Gatsby",
  "author": "F. Scott Fitzgerald",
  "year": 1925,
  "created_at": "2024-03-01T10:30:00Z"
}

---

PUT - Replace Resource

Replaces an entire resource. The client must send the complete representation.

PUT /api/books/456
Content-Type: application/json

{
  "id": 456,
  "title": "The Great Gatsby",
  "author": "F. Scott Fitzgerald",
  "year": 1925,
  "genre": "Classic Fiction"
}

Rules:

• Must be idempotent
• Client sends complete resource representation
• Missing fields may be set to null/default

---

PATCH - Partial Update

Updates specific fields of a resource without replacing the entire representation.

PATCH /api/books/456
Content-Type: application/json

{
  "genre": "American Classic"
}

Rules:

• Only specified fields are updated
• Other fields remain unchanged
• Follows RFC 7386: JSON Merge Patch ↗

---

DELETE - Remove Resource

Removes a resource from the server.

DELETE /api/books/456

Response:

204 No Content

Rules:

• Must be idempotent (deleting twice = same result)
• Return 204 No Content even if resource already deleted
• Avoid 404 Not Found to support retry scenarios

---

Verb Usage Matrix

Endpoint	GET	POST	PUT	DELETE	PATCH
/api/books	List all	Create new	Bulk update (uncommon)	Delete all (dangerous)	Bulk partial update
/api/books/123	Get one	Not allowed	Replace	Delete	Partial update

---

Common Mistakes to Avoid

1. Using GET for operations that modify data

   Bad:  GET /api/books/123/delete
   Good: DELETE /api/books/123

2. Using POST for everything

   Bad:  POST /api/getBookById
   Good: GET /api/books/123

3. Ignoring idempotency

   • PUT should replace the entire resource
   • DELETE should be safe to call multiple times