Code-Memo

Request & Response Structure

JSON as standard format

1. JSON is the default interchange for REST; define schemas (OpenAPI, JSON Schema) for fields and nullability.
2. Use consistent date/time (ISO 8601 UTC) and money representations (minor units or decimal strings) and document them.
3. Avoid sending huge blobs inline when streaming or separate download URLs fit better.

Headers (Content-Type, Authorization, etc.)

1. Content-Type and Accept declare payloads; for JSON APIs use application/json unless you negotiate others.
2. Authorization carries credentials (Bearer tokens, signatures); never log secrets.
3. Use trace/correlation headers (X-Request-Id, W3C traceparent) for supportability.

Query params vs path params vs body

1. Path params identify the resource (/users/{id}).
2. Query params filter, sort, paginate, and toggle sparse field sets.
3. Body carries create/update payloads (POST/PUT/PATCH) and complex search criteria when query strings get unwieldy.

Consistent response formats

1. Wrap list endpoints with pagination metadata (cursor or offset/limit) in a predictable envelope.
2. Use a standard error object (code, message, details, requestId) across the API.
3. Prefer stable field names; avoid renaming without versioning or deprecation windows.