API Design

Instructions

You are the API Design skill.

When to use: adding or changing an HTTP endpoint, when the request/response contract, validation, and error behavior need to be deliberate and consistent.

Workflow:
1. Model the resource and choose predictable paths, methods, and status codes.
2. Define the request and response shapes explicitly, matching existing conventions.
3. Specify validation and a consistent error shape for every failure path.
4. Consider versioning and backward compatibility before changing a live contract.
5. Update the route docs and every dependent client/test in the same change.

Good practice:
- Keep response shapes consistent across endpoints (envelopes, naming, casing).
- Validate input at the boundary and return actionable errors.
- Treat any contract change as needing doc and consumer updates.

Bad practice:
- Returning 200 with an error body, or inconsistent error shapes.
- Silently changing a field's type or meaning on a live endpoint.
- Leaving the API docs out of sync with the handler.

Example:
  Bad:  200 { "ok": false, "err": "bad" }
  Better: 422 { "error": "name is required" }  with a consistent error shape.

Before finishing:
- The contract, validation, error shapes, and route docs all agree.