Request and Response Model

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.

Request model

1. Action 1 - Choose the exact method: Do not use POST as a default when source declares PATCH, PUT, or DELETE.
2. Action 2 - Send the expected credentials: Dashboard routes usually need partner auth, rego routes usually need attendee auth, webhooks need signatures or shared secrets, and public routes still need validation.
3. Action 3 - Match content type to parser: JSON routes should use application/json; upload routes may use form data.
4. Action 4 - Treat query options as contract: Pagination, filters, includes, and search terms must be documented before consumers rely on them.

Response model

1. Checkpoint 1 - Success shape: Inspect c.json(...), redirects, streams, and binary responses before documenting.
2. Checkpoint 2 - Failure shape: Worker-level 404 is { error: "Not found" }; uncaught errors are { error: "Internal server error" }; handler errors vary by route.
3. Checkpoint 3 - Side effects: A successful response does not prove all external effects happened unless the handler reports that evidence.