--- name: http-api description: "Keep HTTP APIs honest: sync OpenAPI contracts with handler behavior, and write or debug end-to-end HTTP integration tests for handlers, middleware, auth, and endpoint contracts. Use when endpoints, schemas, auth, or error shapes change, or HTTP integration tests need adding or fixing." license: GNU GPL v3 metadata: version: 1.4.2 # x-release-please-version owner: mattriley category: testing audience: general-coding-agent maturity: stable kind: task --- # HTTP API ## Use this skill when - The task adds or changes a public HTTP endpoint and the OpenAPI contract must stay aligned. - Request/response schemas, status codes, auth requirements, or documented errors are changing together. - Code and API contract have drifted and the repo needs the correct sync workflow. - HTTP integration tests need adding or fixing for handlers, middleware, auth enforcement, status codes, validation, or side effects. ## Do not use this skill when - The request is a generic REST/OpenAPI tutorial. - The task is only to generate a client SDK from an existing spec with no server-contract change. - The change is internal-only code with no HTTP contract or no OpenAPI surface in play. - The failure is clearly at the unit-test layer with no HTTP involved — use [`testing-workflows`](../testing-workflows/SKILL.md). ## Inputs to gather - Where the API contract lives: - hand-authored spec files - code annotations/types/routes that generate the spec - a hybrid flow that updates both - Validation/generation commands for the repo (`make validate-openapi`, `swagger-cli`, codegen targets, etc.). - The exact endpoint surface being changed: path, method, auth, request body, success responses, error responses. - Whether the endpoint is public/external, internal-only, or intentionally undocumented. ## First move Determine the repo's contract flow before editing anything: spec-first, code-first, or hybrid. Do not assume `openapi.yaml` is the source of truth or that it should be hand-edited. ## Workflow 1. Identify the contract owner. - Read the repo docs, build targets, and generation tooling to see whether the spec is hand-maintained, generated from code, or maintained in both places. 2. Follow the repo's contract path. - **Spec-first repos:** update the OpenAPI contract first, validate it, then implement handlers/middleware/tests to match. - **Code-first repos:** update the handler/types/annotations first, regenerate the spec/artifacts, then verify the generated contract matches the intended behavior. - **Hybrid repos:** update both authored surfaces in the order the repo expects, then run validation/generation to reconcile them. 3. Verify the behavior-contract alignment. - Match auth requirements, request validation, response schemas, status codes, and documented error shapes. - Confirm the changed endpoint is included or intentionally excluded from the OpenAPI surface. 4. Run the repo's API checks. - Validate the spec when the repo has a validator. - Run the relevant integration/unit/contract tests for the changed surface. 5. Integration tests (when adding, fixing, or debugging HTTP-level coverage). - Run the targeted test verbosely and read the real request/response before proposing fixes. - Follow `references/integration-testing-http.md` for the runner, auth fixtures, DB bootstrap, and scoped reruns. - Worked cases are in `references/integration-testing-http-examples.md`; flaky, stateful, or generated-code traps in `references/integration-testing-http-edge-cases.md`. ## Outputs - Updated contract-owner artifacts for the changed API surface, including spec, handler/type inputs, and any generated OpenAPI output the repo expects. - A documented behavior-to-contract alignment for auth requirements, request validation, response schemas, status codes, and error shapes. - Spec validation, generation, and/or API test evidence confirming the handler behavior and OpenAPI contract stay in sync. ## Guardrails - Do not hand-edit generated OpenAPI output in code-first repos; change the source inputs that own it. - Do not change public endpoint behavior without the matching contract update or regeneration. - Auth requirements, status codes, and error shapes must align with the contract owner the repo actually uses. - If the repo has no OpenAPI contract for this surface, do not invent one unless the user asks for that design decision; document the gap instead. - When handler changes also affect generated clients/server stubs, coordinate with the code-generation workflow rather than patching generated artifacts directly. ## Validation - The repo's spec validation or generation step succeeds. - Handler behavior, tests, and contract artifacts agree on auth, schemas, and status codes. - Any generated contract files or checked-in specs show only the expected diff. ## Reference files - Read `references/examples.md` when you need examples of drift repair or endpoint changes that must keep contract and implementation aligned. - Read `references/edge-cases.md` when the repo lacks a spec, uses generated specs, or the request may really be SDK generation or a non-HTTP change.