HTTP verbs, status conventions, REST shape, payload discipline and security defaults for JSON APIs in 2026. All rows are plain text - search to filter, click Copy to grab the pattern.
Reference rack
STATUSREADY
ROWS48
NETWORKLOCAL
MODEREFERENCE
| Item / pattern | What it means / how to use it | |
|---|---|---|
| GET /resource | Fetch a resource or collection - safe, cacheable, no side effects. | |
| POST /resource | Create a new resource; the server assigns the id. | |
| PUT /resource/{id} | Replace the whole resource - idempotent. | |
| PATCH /resource/{id} | Partial update - send only the changed fields. | |
| DELETE /resource/{id} | Remove the resource; often idempotent server-side. | |
| HEAD / OPTIONS | Headers-only response / CORS preflight and advertised methods. | |
| 200 OK | Success with a response body. | |
| 201 Created | A resource was created; include a Location: /resource/{id} header. | |
| 204 No Content | Success with an empty body - deletes and silent updates. | |
| 400 Bad Request | Malformed request or schema failure; return your error model. | |
| 401 Unauthorized / 403 Forbidden | Missing or expired credentials vs authenticated-but-not-allowed. | |
| 404 Not Found | Unknown resource or id. | |
| 409 Conflict | State conflict, for example a duplicate unique value. | |
| 422 Unprocessable Entity | Well-formed but failed business validation; list field-level errors. | |
| 429 Too Many Requests | Rate limited; set a Retry-After header. | |
| 5xx statuses | Server-side failures - never leak stack traces or internals. | |
| Plural nouns, no verbs | /users not /getUser; actions become sub-resources like /users/{id}/activate. | |
| Max two nesting levels | /users/{id}/orders; deeper nesting usually hides a missing resource. | |
| Filter, page and sort via query params | "?status=active&page=2&limit=20&sort=-created". | |
| Field selection | "?fields=id,name" trims large collection payloads. | |
| Idempotency keys | Clients send an Idempotency-Key header on POST/PUT so retries are safe. | |
| Version the contract | /v1/ prefix or an Accept header; never change semantics silently. | |
| Pagination envelope | Return { "data": [...] , "paging": { "next": "...", "limit": 20, "total": 412 } }. | |
| List responses | wrap arrays in { "data": [...] } - a top-level array breaks forward compatibility. | |
| Single objects | return { "data": { ... } } for consistency with list envelopes. | |
| Error model | Use { "error": { "code": "VALIDATION", "message": "...", "field": "email" } }. | |
| Stable ids | Prefer opaque strings over sequential integers to avoid enumeration attacks. | |
| Timestamps ISO 8601 UTC | "created_at": "2026-09-08T04:30:00Z" - always include the timezone. | |
| camelCase or snake_case | Pick one naming convention and document it; don't mix. | |
| null vs missing | null = known empty, absent = not provided - PATCH must treat them differently. | |
| Money as integers or decimal strings | cents (int) or "19.99" (string) - never binary floats. | |
| Enums as stable strings | Prefer "status": "active" over opaque integers for safe evolution. | |
| Explicit schema guard | Add "schema": "1.2" when clients can't ship fast enough. | |
| Positive boolean naming | "is_active", "has_billing" read better than negated flags. | |
| Recalculate server-side | Never trust client-supplied sums or ranges; recompute authoritatively. | |
| Authorization: Bearer <token> | The standard placement for JWTs and tokens. | |
| Scoped tokens | "scope: api:read" - grant the least privilege. | |
| Accept / Content-Type: application/json | Declare and require JSON on the wire. | |
| Validate Content-Type before parsing | Reject anything unexpected with 415. | |
| Layer validation | Schema types + business rules + DB uniqueness, in that order. | |
| Rate limit per key/IP | Separate anonymous and authenticated quotas. | |
| CORS allowlist | Reflect an expected Origin list, not "*" with credentials. | |
| HTTPS only + HSTS | Strip plain HTTP; non-negotiable for any API in 2026. | |
| curl smoke test | "curl -si -H \"Authorization: Bearer $TOKEN\" https://api.example.com/v1/users?limit=1". | |
| Contract tests with gold files | Diff responses against frozen JSON snapshots per endpoint. | |
| Deprecation calendar | Announce, run both versions, then 410 after N months. | |
| Additive-only in a minor version | New fields and endpoints only; removals need a version bump. | |
| Cursor pagination over offsets | ?cursor=<opaque> stays stable when rows are inserted mid-page. |