HTTP and REST API Design

Good REST APIs model resources with plural nouns (/orders/{id}/items), use HTTP methods for semantics (GET read, POST create, PUT replace, PATCH partial update, DELETE remove), return meaningful status codes (201 + Location, 204, 400/422, 401/403, 404, 409, 429), and stay consistent in naming, dates (ISO-8601 UTC), money (minor units + currency) and errors (Problem Details). Design from client use cases, not database tables.

POST /v1/orders HTTP/1.1
Content-Type: application/json
Idempotency-Key: 6f1c2a9e-...

{"items":[{"sku":"MUG-01","qty":2}],"currency":"EUR"}

HTTP/1.1 201 Created
Location: /v1/orders/ord_8812
Content-Type: application/json

{"id":"ord_8812","status":"pending","total":{"amount":2400,"currency":"EUR"},"created_at":"2026-10-10T09:12:44Z"}

Common pitfalls

• Verbs in URLs (/getOrders).
• 200 OK with an error body.
• Exposing internal database structure as the API.

Key points

• Resources + HTTP semantics
• Correct status codes
• Consistent conventions everywhere

Further reading: Microsoft REST API Guidelines