Request and Response Patterns

End-to-end developer runbook

1. Step 1 - Confirm the API area: Identify the product area, route module, endpoint path, and consumer before writing or calling code.
2. Step 2 - Read the endpoint contract: Check method, auth, parameters, response, errors, side effects, and related docs.
3. Step 3 - Prepare authentication and input: Use the right session, bearer token, webhook secret, or internal header. Validate body and query data before sending it.
4. Step 4 - Make the request: Call the endpoint from the correct origin and environment. Keep credentials and secrets out of logs.
5. Step 5 - Verify response, side effects, and records: Confirm status code, response shape, database records, external side effects, and audit evidence.
6. Step 6 - Add tests, docs, and handoff notes: Update route inventory, consumer notes, and certification checks before depending on the change.

Pattern checklist

1. Action 1 - Use explicit methods: Keep reads as GET, creates as POST, partial updates as PATCH, replacements as PUT, and removals as DELETE when possible.
2. Action 2 - Validate body before use: Parse JSON or form data once and reject invalid input with a clear status and error message.
3. Action 3 - Return stable keys: Consumers should not depend on incidental Supabase column names unless documented.
4. Action 4 - Include IDs for changed records: Mutation responses should let callers verify what changed.
5. Action 5 - Keep binary responses obvious: Image proxy, downloads, and release routes need content type and cache notes.

Checkpoint list

1. Checkpoint 1 - Example request exists: Docs show a realistic request.
2. Checkpoint 2 - Example response exists: Docs show success and failure shapes.
3. Checkpoint 3 - Unknowns are labelled: Missing proof is marked Unknown from source, not guessed.