HTTP API Request Methods

http api rest reference

---

Method Properties

Method	Safe	Idempotent	Cacheable	Request Body	Response Body	Typical Use Case
GET	Yes	Yes	Yes	No	Yes	Retrieve data
HEAD	Yes	Yes	Yes	No	No	Get headers only (check existence)
OPTIONS	Yes	Yes	No	No	Yes	CORS preflight, discover methods
TRACE	Yes	Yes	No	No	Yes	Debug (usually disabled)
PUT	No	Yes	No	Yes	Yes	Replace entire resource
DELETE	No	Yes	No	No	Yes	Remove resource
POST	No	No	Conditional	Yes	Yes	Create resource, trigger action
PATCH	No	No	Conditional	Yes	Yes	Partial update
CONNECT	No	No	No	No	Yes	Establish tunnel (HTTPS proxy)

Key Definitions

• Safe: Doesn’t modify server state (read-only)
• Idempotent: Multiple identical requests have same effect as single request
• Cacheable: Response can be stored and reused

---

Method Details

GET

Retrieve a resource. Never modify data with GET.

GET /api/users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer token123

Expected responses:

• 200 OK - Resource found
• 404 Not Found - Resource doesn’t exist
• 304 Not Modified - Cached version still valid

---

POST

Create a new resource or trigger a non-idempotent action.

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{"name": "John", "email": "john@example.com"}

Expected responses:

• 201 Created - Resource created (include Location header)
• 202 Accepted - Async processing started
• 400 Bad Request - Invalid request body
• 409 Conflict - Resource already exists

---

PUT

Replace an entire resource. Creates if doesn’t exist (upsert).

PUT /api/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{"name": "John Updated", "email": "john@example.com", "role": "admin"}

Expected responses:

• 200 OK - Updated and returning resource
• 204 No Content - Updated successfully
• 201 Created - Created new resource
• 404 Not Found - Resource not found (if not supporting upsert)

---

PATCH

Partial update - only send fields to change.

PATCH /api/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{"role": "admin"}

Expected responses:

• 200 OK - Updated and returning resource
• 204 No Content - Updated successfully
• 400 Bad Request - Invalid patch
• 404 Not Found - Resource not found

---

DELETE

Remove a resource.

DELETE /api/users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer token123

Expected responses:

• 204 No Content - Deleted successfully
• 200 OK - Deleted, returning deleted resource
• 404 Not Found - Resource doesn’t exist
• 409 Conflict - Cannot delete (dependencies)

---

HEAD

Like GET but returns only headers (no body). Useful for checking resource existence or metadata without downloading.

HEAD /api/files/large-report.pdf HTTP/1.1
Host: api.example.com

Expected responses:

• 200 OK - Resource exists
• 404 Not Found - Resource doesn’t exist

---

OPTIONS

Discover what methods and headers are allowed. Used by browsers for CORS preflight.

OPTIONS /api/users HTTP/1.1
Host: api.example.com
Origin: https://frontend.example.com

Expected responses:

• 200 OK or 204 No Content
• Returns Allow header listing supported methods
• For CORS: Access-Control-Allow-* headers

---

PUT vs PATCH

Aspect	PUT	PATCH
Scope	Replace entire resource	Update specific fields
Missing fields	Set to null/default	Left unchanged
Idempotent	Yes	No (can be, but not guaranteed)
Body	Complete resource	Only changed fields

Example Difference

Original resource:

{"id": 1, "name": "John", "email": "john@example.com", "role": "user"}

PUT with {"name": "Jane"}:

{"id": 1, "name": "Jane", "email": null, "role": null}

PATCH with {"name": "Jane"}:

{"id": 1, "name": "Jane", "email": "john@example.com", "role": "user"}

---

POST vs PUT

Aspect	POST	PUT
URL target	Collection (/users)	Specific resource (/users/123)
ID assignment	Server assigns ID	Client specifies ID
Idempotent	No	Yes
Create	Yes	Yes
Update	Sometimes (append)	Yes (replace)

When to Use

Use POST when:

• Creating a resource where server assigns the ID
• Triggering an action (send email, process payment)
• Request is not idempotent

Use PUT when:

• Client knows the full resource URL
• Replacing the entire resource
• Need idempotent creates (retry-safe)

---

Common Patterns

Bulk Operations

POST /api/users/bulk
Content-Type: application/json
 
{"users": [{"name": "User1"}, {"name": "User2"}]}

Actions on Resources

POST /api/orders/123/cancel
POST /api/users/123/reset-password

Search (when query too complex for GET)

POST /api/users/search
Content-Type: application/json
 
{"filters": {"age": {"gte": 21}}, "sort": "name"}

---

Status Codes by Method

Method	Success	Common Errors
GET	200, 304	401, 403, 404
POST	201, 202	400, 401, 403, 409, 422
PUT	200, 201, 204	400, 401, 403, 404, 409
PATCH	200, 204	400, 401, 403, 404, 409
DELETE	200, 204	401, 403, 404, 409
HEAD	200	401, 403, 404
OPTIONS	200, 204	-