HTTP Methods, Status Codes & Query Parameters Masterclass

Safe vs. Idempotent Methods (RFC 9110)

Before designing an API, every backend engineer must internalize two foundational concepts defined in RFC 9110:

1. Safe Methods: Methods that do not mutate server state. Calling them should have no persistent side effects. (e.g. GET, HEAD, OPTIONS).
2. Idempotent Methods: Methods where making multiple identical requests produces the exact same server state as making a single request. (e.g. GET, PUT, DELETE). Mathematically: $f(f(x)) = f(x)$.

The RFC 9110 Method Matrix

Method	Safe?	Idempotent?	Typical Request Body	Standard Success Status
GET	✅ Yes	✅ Yes	No	200 OK
HEAD	✅ Yes	✅ Yes	No	200 OK (Headers only, no body)
POST	❌ No	❌ No	Yes (Resource representation)	201 Created or 200 OK
PUT	❌ No	✅ Yes	Yes (Complete replacement)	200 OK or 204 No Content
PATCH	❌ No	❌ (Depends)	Yes (Partial delta)	200 OK
DELETE	❌ No	✅ Yes	No	204 No Content or 200 OK

---

PUT vs. POST: The Definitive Architectural Rules

The difference between PUT and POST is one of the most common confusion points in web development. Here is the practitioner breakdown:

Dimension	POST	PUT
URI Target	Points to a collection (/v1/orders)	Points to an individual resource (/v1/orders/ord_123)
ID Assignment	Server assigns ID (ord_123)	Client specifies target ID
Idempotency	❌ Non-Idempotent (Calling 3 times creates 3 orders)	✅ Idempotent (Calling 3 times results in the same state)
Payload Scope	Submits new data to be processed	Replaces the target resource in its entirety
Safety on Retries	Risky (Requires Idempotency-Key to avoid double charges)	Safe (Client can retry network timeouts freely)

Real-World Example: Creating vs Replacing

Use POST when the server generates the identifier:

POST /v1/articles HTTP/2
Content-Type: application/json

{
  "title": "Mastering REST Query Parameters"
}

# Response:
HTTP/2 201 Created
Location: /v1/articles/art_98234a

Use PUT when the client defines or replaces the exact URI:

PUT /v1/articles/art_98234a HTTP/2
Content-Type: application/json

{
  "title": "Mastering REST Query Parameters",
  "content": "Full article markdown...",
  "published": true
}

# Response:
HTTP/2 200 OK

Crucial Warning on PUT: If an existing article has tags ["tech", "api"] and you send a PUT request omitting the tags field, the server is expected to clear or reset tags to null/empty! If you only want to update published: true without erasing tags, use PATCH instead.

---

HTTP GET Query Parameters: Production Best Practices

GET requests cannot carry a request body by RFC convention. Therefore, all search, filtering, sorting, field selection, and pagination parameters must travel in the URL query string.

Here is how production APIs (like Stripe, GitHub, Shopify) standardize query strings:

---

1. Filtering Parameters

Support both exact matching and range filters using structured brackets:

# Exact match filtering
GET /v1/orders?status=shipped&payment_method=card

# Range filtering (timestamps, prices)
GET /v1/orders?created_at[gte]=2026-01-01T00:00:00Z&created_at[lte]=2026-01-31T23:59:59Z

# Multi-value (OR) filtering
GET /v1/products?category=electronics,books

---

2. Sorting Conventions

Use a clean sort parameter. The industry standard is to prefix descending fields with a hyphen (-):

# Sort by creation date descending (newest first)
GET /v1/orders?sort=-created_at

# Multi-field sorting: status ascending, then priority descending
GET /v1/tasks?sort=status,-priority

---

3. Sparse Fieldsets (Field Picking)

Prevent over-fetching by allowing clients to request only the specific fields their UI needs. This provides GraphQL-like bandwidth savings over standard REST:

# Retrieve only the id, name, and email fields
GET /v1/users?fields=id,name,email

---

4. Search & URL Encoding Rules

When passing free-text queries, always apply standard RFC 3986 percent-encoding:

# Query: "REST API & JSON"
GET /v1/search?q=REST%20API%20%26%20JSON

• Spaces should be encoded as %20 (or + in application/x-www-form-urlencoded).
• Reserved characters like &, ?, #, and / must always be escaped.

---

5. CDN Caching & Query Parameter Normalization

Because edge CDNs (Cloudflare, Fastly, AWS CloudFront) use the entire URL as the cache key by default, differing query parameter orders can result in unnecessary cache misses:

Request A: /v1/products?category=shoes&color=red   # Cache MISS -> Stored in CDN
Request B: /v1/products?color=red&category=shoes   # Cache MISS -> Duplicate origin query!

Practitioner Pro Tip: In Cloudflare or your API Gateway, enable Query String Normalization / Alphabetical Sorting so that both requests share the exact same cached response key.

---

The 5 Status Code Classes

HTTP status codes are 3-digit integers categorized by their first digit:

2xx Success: The Request Succeeded

• 200 OK: Standard success returning a body.
• 201 Created: Resource created; always return a Location header.
• 202 Accepted: Request enqueued for background processing (e.g. batch exports).
• 204 No Content: Succeeded, with no response body (standard for DELETE).

3xx Redirection: Resource Relocated

• 301 Moved Permanently: The URI has permanently changed.
• 304 Not Modified: The client’s cached representation matches the server (ETag). Saves bandwidth.

4xx Client Error: The Caller Made a Mistake

• 400 Bad Request: Malformed JSON syntax or unparseable input.
• 401 Unauthorized: Authentication is missing or invalid credentials supplied.
• 403 Forbidden: Authenticated, but lacks permission for this action (RBAC).
• 404 Not Found: The requested resource does not exist.
• 409 Conflict: State collision (e.g. unique slug already taken).
• 422 Unprocessable Content: Valid JSON syntax, but business logic validation failed.
• 429 Too Many Requests: Rate limited! Must include Retry-After: 60 header.

5xx Server Error: The Server Failed

• 500 Internal Server Error: Unhandled exception or unexpected server crash.
• 502 Bad Gateway: Proxy received invalid response from upstream.
• 503 Service Unavailable: Server overloaded or circuit breaker tripped.
• 504 Gateway Timeout: Upstream service failed to respond in time.