🚀API & Web Architecture⏱️ 15 min read•Updated October 2026

REST API Architecture, HTTP Status Codes & cURL Integration Runbook

The pragmatic production runbook for RESTful API engineering: Resource URL grammar, idempotent HTTP methods (GET, PUT, DELETE) vs POST, the definitive HTTP status code decision tree, and high-velocity cURL CLI debugging.

#REST#API#HTTP#cURL#Backend#Web Development#Architecture

1. Resource URI Grammar: Nouns, Plurals & Hierarchy

URIs identify resources, not actions. Avoid putting verbs in URL paths (e.g. /getUser or /deleteOrder). Use plural nouns to represent collections, and express nested ownership relationships hierarchically.

Pattern	Anti-Pattern (Verb-based)	Production REST Pattern (Resource-based)
`Fetch all records`	GET /api/getUsers	GET /api/v1/users
`Create single record`	POST /api/createUser	POST /api/v1/users
`Fetch nested resource`	GET /api/getUserOrders?id=12	GET /api/v1/users/12/orders
`Cancel specific order`	POST /api/cancelOrder?id=99	POST /api/v1/orders/99/cancellation (or PATCH status)

2. HTTP Methods & Idempotency Rules

An HTTP method is idempotent if executing it multiple times produces the exact same server state as executing it once. Network retries must only be automated on idempotent operations.

HTTP Method	Safe? (Read-only)	Idempotent? (Safe to auto-retry)	Semantics
`GET`	Yes	Yes	Retrieves a representation without modifying state
`POST`	No	No	Creates a new sub-resource or triggers side-effects
`PUT`	No	Yes	Replaces the entire target resource state
`PATCH`	No	Not guaranteed (depends on the patch format)	Applies partial modifications to a resource
`DELETE`	No	Yes	Removes the resource; repeat calls return 404 or 204 but leave the same server state

3. The Definitive HTTP Status Code Decision Tree

Using correct status codes allows HTTP caches, reverse proxies, browsers, and API SDKs to handle errors deterministically without parsing JSON error messages.

Status Code Selection Cheat Sheet

/* 2xx SUCCESS:
 * 200 OK           : Standard success with response body (GET, PUT, PATCH)
 * 201 Created      : New resource created; include "Location: /api/items/42" header (POST)
 * 204 No Content   : Success with no response body (DELETE, empty PUT/PATCH)
 *
 * 4xx CLIENT ERRORS:
 * 400 Bad Request  : Malformed JSON syntax or unparseable payload
 * 401 Unauthorized : Authentication missing or invalid (Needs credentials)
 * 403 Forbidden    : Authenticated, but lacks permission to this specific resource
 * 404 Not Found    : Resource does not exist (or hidden for security reasons)
 * 409 Conflict     : Unique constraint violation (e.g. email already registered)
 * 422 Unproc Entity: Well-formed JSON, but fails schema validation (e.g. invalid email format)
 * 429 Too Many Req : Rate limit reached; MUST include "Retry-After: 60" header
 *
 * 5xx SERVER ERRORS:
 * 500 Server Error : Unhandled exception or code crash (Alert on-call engineers!)
 * 502 Bad Gateway  : Upstream service/microservice unreachable from proxy
 * 503 Unavailable  : Planned maintenance or downstream database capacity exhaustion
 * 504 Gateway T/O  : Upstream took longer than proxy timeout (e.g. > 60s)
 */

401 means "Unauthenticated", whereas 403 means "Unauthorized / Forbidden".

4. Standardized Problem Details (RFC 7807)

Never return arbitrary, ad-hoc JSON error structures like { "err": "Something broke" }. Adopt the standardized RFC 7807 / RFC 9457 "application/problem+json" specification.

RFC 7807 Standard Error Response Payload

// HTTP/1.1 422 Unprocessable Content
// Content-Type: application/problem+json
{
  "type": "https://api.example.com/errors/invalid-parameters",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The provided parameters failed validation rules.",
  "instance": "/v1/orders/create",
  "invalid_params": [
    { "name": "quantity", "reason": "Must be an integer greater than 0" },
    { "name": "currency", "reason": "Unsupported currency code: EUR, USD expected" }
  ]
}

Standardized error formats enable client SDKs to render consistent error banners and field highlights.

5. High-Velocity cURL CLI Debugging Runbook

Debug endpoints, inspect raw TLS handshakes, examine exact response headers, and profile network latency directly from the command line.

Essential cURL Flags & Profiling Commands

# 1. Verbose inspection of request headers, response headers, and TLS handshake
curl -Iv https://api.example.com/v1/health

# 2. POST JSON payload with custom bearer authentication
curl -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"sku": "PRO-99", "quantity": 2}'

# 3. Profile exact HTTP latency phases (DNS, TCP, TLS, TTFB, Total)
curl -w "@curl-format.txt" -o /dev/null -s https://api.example.com/v1/users

# Format template (curl-format.txt):
# time_namelookup:  %{time_namelookup}s\n
# time_connect:     %{time_connect}s\n
# time_appconnect:  %{time_appconnect}s\n
# time_starttransfer: %{time_starttransfer}s\n
# time_total:       %{time_total}s\n

curl -Iv reveals response codes, Set-Cookie attributes, rate-limit headers, and HTTP/2 multiplexing streams.

🧰