Build with DEX · 32 reference entries
Design understandable HTTP contracts with validation, access checks, bounded work, useful errors and deliberate caching.
API examples need the application's real session, validation and storage layers. These notes explain the design decisions and checks; adding them to the reference library does not enable a service or certify a live endpoint.
Choose an entry or use Find on page to look for a term. Each number identifies an educational reference; production checks need their own recorded result.
WEB-API-001
Choose stable resource URLs and use methods according to their semantics. Document the allowed operations and response shapes for each resource.
GET /example-api/lessons
GET /example-api/lessons/42
POST /example-api/lessonsDocumentation: API and security documentation
WEB-API-002
GET and HEAD should retrieve information without performing a requested state change. A crawler or retry may repeat them.
GET /example-api/lessons/42 → read a lesson
POST /example-api/lessons → create a lessonDocumentation: API and security documentation
WEB-API-003
An idempotent operation has the same intended effect when repeated. It can still return different response details as the resource state changes.
PUT /example-api/preferences/theme
Body: {"theme":"system"}Documentation: API and security documentation
WEB-API-004
A create operation may need an application idempotency contract. Store a key and the result atomically so a retry cannot create a duplicate.
Contract example: a client supplies one request key for a create attempt; the server returns the stored result for a matching replay.Documentation: API and security documentation
WEB-API-005
Choose a status that represents the outcome. Clients need to distinguish an invalid request, missing resource and temporary service failure.
200: successful read
201: resource created
400: invalid request
404: missing resource
503: temporary unavailabilityDocumentation: API and security documentation
WEB-API-006
Reject unsupported methods explicitly and include the supported methods in the Allow header where required.
HTTP/1.1 405 Method Not Allowed
Allow: GET, HEADDocumentation: API and security documentation
WEB-API-007
Validate the incoming format and declare the outgoing one. Do not interpret an arbitrary body as JSON without checking the contract.
Request: Content-Type: application/json
Response: Content-Type: application/json; charset=utf-8Documentation: API and security documentation
WEB-API-008
Return a predictable error structure with a useful title and status. Problem Details provides a standard vocabulary for API errors.
Content-Type: application/problem+json
{"type":"about:blank","title":"Invalid request","status":400,"detail":"The page size must be between 1 and 100."}Documentation: API and security documentation
WEB-API-009
Validate the type, range and permitted values of every accepted field. Browser checks improve the interface but do not enforce an API contract.
const limit = Number(url.searchParams.get("limit") ?? "25");
if (!Number.isInteger(limit) || limit < 1 || limit > 100) return invalidRequest();Documentation: API and security documentation
WEB-API-010
Limit body size before expensive parsing and check the actual bytes received. A Content-Length value alone is not a complete enforcement mechanism.
Reject a body that exceeds the endpoint's documented limit with an appropriate 413 response.Documentation: API and security documentation
WEB-API-011
Verify who is calling, then check permission for the specific operation. A valid session does not grant access to every resource.
Request → verify session → check allowed action → load authorised resource → return permitted fieldsDocumentation: API and security documentation
WEB-API-012
Scope a private record lookup to the authenticated user's identity. Check permissions on every request, including read and update routes.
SELECT id, title FROM notes WHERE id = ? AND owner_id = ?;Documentation: API and security documentation
WEB-API-013
Build public and member responses from an allowlist of intended fields. A new internal database column must not silently become an API field.
const response = { id: record.id, title: record.title, status: record.status };Documentation: API and security documentation
WEB-API-014
Use secure, HttpOnly cookies with an appropriate SameSite policy. Keep session scope and expiry aligned with the authentication design.
Set-Cookie: __Host-session=opaque-value; Path=/; Secure; HttpOnly; SameSite=LaxDocumentation: API and security documentation
WEB-API-015
CORS controls which browser origins can read a cross-origin response. It does not replace authentication or permission checks.
Access-Control-Allow-Origin: https://example.com
Vary: OriginDocumentation: API and security documentation
WEB-API-016
For cookie-authenticated state changes, apply the application's CSRF protections and origin checks. Do not assume a JSON body or CORS policy solves every case.
Validate the request origin and the application's anti-CSRF token before changing account state.Documentation: API and security documentation
WEB-API-017
Keep private keys and privileged credentials in server-side secret storage. Browser code, public URLs and response bodies are public delivery surfaces.
Browser → authenticated application endpoint
Server → upstream service using a protected server credentialDocumentation: API and security documentation
WEB-API-018
An endpoint that fetches a user-supplied URL needs a deliberate destination policy. Validate redirects and prevent access to internal or privileged network targets.
Accept only the intended scheme and approved destinations; re-check each permitted redirect before following it.Documentation: API and security documentation
WEB-API-019
Apply limits appropriate to the caller and operation. Expensive work may need a stricter allowance than a cached public read.
HTTP/1.1 429 Too Many Requests
Retry-After: 30Documentation: API and security documentation
WEB-API-020
Retry only failures and operations that are safe to repeat. Use a retry limit, delay and jitter rather than immediate unlimited repetition.
Retry policy: at most 2 additional safe-read attempts; honour Retry-After; stop after the overall deadline.Documentation: API and security documentation
WEB-API-021
Give upstream work a time budget and cancel obsolete work where supported. Map an upstream timeout to a clear response and recovery path.
const response = await fetch(upstreamUrl, { signal: AbortSignal.timeout(8000) });Documentation: API and security documentation
WEB-API-022
Enforce a maximum page size and return enough information to continue. A client-provided limit should never permit an unbounded query.
{"items":[{"id":"42","title":"HTML"}],"nextCursor":"opaque-cursor"}Documentation: API and security documentation
WEB-API-023
Use a deterministic tie-breaker when a primary sort value is not unique. The pagination cursor must preserve the same ordering contract.
ORDER BY published_at DESC, id DESCDocumentation: API and security documentation
WEB-API-024
Accept only recognised filter and sort values. Bind data values and map approved sort names to fixed SQL fragments.
const sorts = { newest: "created_at DESC, id DESC", title: "title ASC, id ASC" };
const order = sorts[requestedSort] ?? sorts.newest;Documentation: API and security documentation
WEB-API-025
Choose a policy based on whether the response is public, user-specific or sensitive. Ensure shared caches cannot serve one person's data to another.
For a sensitive account response:
Cache-Control: private, no-storeDocumentation: API and security documentation
WEB-API-026
Use a validator such as ETag to let clients ask whether a representation has changed. Return a body only when required by the request outcome.
Response: ETag: "lesson-v3"
Next request: If-None-Match: "lesson-v3"
Unchanged response: 304 Not ModifiedDocumentation: API and security documentation
WEB-API-027
When response content depends on a request header, declare the relevant variation for caches. Avoid uncontrolled variation that destroys useful reuse.
Vary: Accept-Encoding
For dynamic origin-specific CORS responses, also consider Origin.Documentation: API and security documentation
WEB-API-028
Assign a request identifier and connect it to server diagnostics. Log necessary facts while excluding credentials and sensitive request content.
Diagnostic fields: request ID, route, status, elapsed time and a non-sensitive error category.Documentation: API and security documentation
WEB-API-029
Give clients an actionable message while keeping stack traces, SQL text and secret configuration out of public error bodies.
{"error":{"code":"TEMPORARILY_UNAVAILABLE","message":"This request could not finish. Try again shortly."}}Documentation: API and security documentation
WEB-API-030
Verify the sender using its documented signature scheme, then handle repeated deliveries idempotently. Preserve the raw body when the signature contract requires it.
Receive raw body → verify signature and timestamp → check delivery ID → apply the event once.Documentation: API and security documentation
WEB-API-031
Document contract changes and keep existing consumers working through an intentional migration. Test old and new response shapes during a supported transition.
Change record: affected endpoint, compatibility period, replacement field and migration instructions.Documentation: API and security documentation
WEB-API-032
Test normal requests and realistic failure cases against the implemented endpoint. An example in documentation is not proof of live behaviour.
Record: unauthenticated, wrong-owner, invalid-input, oversized-body, rate-limit, success and upstream-failure outcomes.Documentation: API and security documentation
Reviewed . Send a correction through contact and corrections, including the entry number and supporting documentation.
Explore offers, save a shortlist and buy with the retailer.
Confirm current prices and offer terms with the retailer. Device saves start in this browser. Account sync is optional.
Read what recorded checks establish and what remains unconfirmed.
Country labels do not confirm delivery or convert prices.
Prepare a report to review and send yourself. Preparing it does not send it.
Open the tour on the guide page when you choose. You can skip or close it at any time.