Improve API

Operation

Implement the requested change and verify its directly affected behavior.

Goal

Complete the selected API contract from its defining schema/handler through directly affected persistence, errors and consumers. The correction may be small; it is complete when the same accepted behavior holds at every affected boundary.

Scope selection

• If the user named an endpoint, integration, client failure, schema, webhook, SDK call, or contract issue, improve that API surface and directly affected consumers.
• If the request is broad, inspect the main API seams and apply the highest-confidence improvement with contract, safety, or developer-experience impact.
• Include related validation, error, idempotency, permission, observability, docs, and tests when they belong to the same contract.
• Avoid unrelated endpoint redesigns, mass API versioning, dependency changes, and database rewrites unless required by the selected contract fix.

Change targets

• Request/response schema clarity, required/optional/null semantics, type coercion, defaults, pagination, sorting, filtering, and versioning behavior.
• Validation boundary: reject malformed input close to the API edge while keeping domain invariants in the owner layer.
• Error model: stable status codes, machine-readable error codes, safe messages, retryability, conflict handling, and not-found/forbidden distinction when security allows it.
• Side effects: idempotency keys, duplicate prevention, transaction boundaries, retries, partial failure, webhooks, background jobs, and cache/index invalidation.
• Consumer contract: generated clients, frontend callers, bot/tool callers, docs/examples, fixtures, and integration tests.
• Operational behavior: rate limits, timeouts, logging, tracing, metrics, and safe diagnostics where repo patterns exist.

Implementation principles

• Preserve public contracts unless the task explicitly authorizes a breaking change.
• Prefer one source of truth for schemas and shared types over duplicated literals.
• Keep UI/client promises aligned with backend behavior.

Validation

Run repository-native checks for the touched API surface. Prefer endpoint/unit/integration tests that exercise success, validation failure, auth/permission failure, conflict/idempotency, and consumer behavior. If external services or credentials block full validation, state exactly what was not exercised.

First pin the failing request/state and expected consumer interpretation. Correct the authoritative schema, validation, service, transaction or serializer; regenerate dependent clients from their source when needed. Replay the original case and valid control, inspecting effects independently of status codes. A remaining compatibility failure enters the contract-evolution workflow; accepted behavior proceeds to Patch Checking on the full resulting change.