HTTP Methods & Resources
| Item | Description |
|---|
GET /users | List users collection (paginated) |
GET /users/123 | Retrieve single user |
POST /users | Create a new user (body contains resource) |
PUT /users/123 | Full replacement of user 123 |
PATCH /users/123 | Partial update of user 123 |
DELETE /users/123 | Remove user 123 |
HEAD /users/123 | Get headers only (check existence, Last-Modified) |
OPTIONS /users | Discover allowed methods (CORS preflight) |
Status Codes for APIs
| Item | Description |
|---|
200 OK | Successful GET, PUT, PATCH |
201 Created | Successful POST — include Location header with new URL |
202 Accepted | Async operation queued — return status endpoint |
204 No Content | Successful DELETE (no body) |
400 Bad Request | Malformed JSON, invalid query parameters |
401 Unauthorized | Missing or invalid authentication |
403 Forbidden | Valid auth but insufficient permissions |
404 Not Found | Resource doesn't exist |
409 Conflict | Duplicate or version conflict (optimistic locking) |
422 Unprocessable | Validation errors — return structured error details |
429 Too Many Requests | Rate limit — include Retry-After and X-RateLimit-* headers |
Authentication Patterns
| Item | Description |
|---|
API Keys | Simple: X-API-Key header. Good for server-to-server. Rotatable. |
Bearer Token (JWT) | Stateless auth with claims. Use short expiry + refresh tokens. |
OAuth 2.0 | Delegated authorization. Authorization Code flow for user-facing apps. |
HMAC Signing | Validates integrity + identity via signed request (AWS Signature V4) |
mTLS | Mutual TLS — both client and server present certificates |
Versioning & Pagination
| Item | Description |
|---|
URL versioning | /v1/users (most explicit, easy to route) |
Header versioning | Accept: application/vnd.api.v1+json (cleaner URLs) |
Query param | /users?version=1 (simple but pollutes URL) |
Offset pagination | ?offset=0&limit=20 (simple but drifts on inserts) |
Cursor pagination | ?cursor=abc123&limit=20 (stable, recommended) |
Link header | Standard: Link: ; rel="next" for discoverable pagination |
Pro Tip: Use plural nouns for collections: /users not /getUsers. Nest resources sparingly — max 1 level deep (/users/123/orders is fine; /users/123/orders/456/items is not).