goberomsu/craft-skills/api

api

Define a public HTTP contract before handlers, schemas, or client calls. A contract is complete when its published behavior is preserved or its versioned migration is explicit, and the documented requests and responses can be exercised by clients.

Contract gate

Inspect the repository's published API before choosing a convention. Record its URL base, success envelope, pagination model, field naming, and error shape from routes, clients, API descriptions, and deployed examples. Preserve that incumbent contract for existing APIs.

Change a published contract only in an explicitly scoped version or migration. State the affected clients, compatibility behavior, rollout or deprecation path, and how clients verify the transition. Do not call an undocumented or unobserved surface greenfield.

For a greenfield API or an explicitly new version, apply the defaults in conventions.md. That reference owns URL, DTO, naming, and pagination rules, plus the drift audit for an incumbent surface, method completeness, and the client-side normalizer. Apply error-contract.md for failure behavior; it owns the greenfield problem shape, codes, mapping, sanitization, and the single-discriminator rule.

When two components inside one system agree on a shape by convention — an HTTP path hard-coded on both sides, or a file one writes and another parses — read interface-ownership.md. It owns provider-and-consumer ownership and the round-trip contract test that catches drift; principle-testing owns where that test lives and how it is sized.

Verification

• [ ] Repository evidence identifies the incumbent contract, or explains why the API is genuinely greenfield.
• [ ] Existing endpoints preserve their published URL, envelope, pagination, naming, and error behavior.
• [ ] Any public-contract change names its version or migration scope and client-compatibility note.
• [ ] New or explicitly versioned surfaces follow the relevant convention and error references.
• [ ] Exercise representative success, empty or next-page, expected-failure, and sanitized unexpected-failure scenarios through the contract boundary.
• [ ] Structured errors use exactly one discriminator key across the surface, and the drift greps in references/conventions.md return only allowlisted exceptions.
• [ ] Media routes answer HEAD with the same headers as GET and zero bytes, verified by request rather than assumed from the framework.
• [ ] Every success envelope has a client normalizer that rejects an unknown shape, with a test that fails on one; no result is cast into its type.
• [ ] Any implicit interface between two components has a named provider, a named consumer, and a round-trip contract test.

Boundaries

Route service structure, database migration strategy, ORM selection, and persistence implementation to principle-backend. Route UI data fetching, rendering, and client state to principle-frontend; this skill owns only the wire shape a client parses and the normalizer that rejects an unknown one. Route test taxonomy and fixture strategy to principle-testing; this skill owns the contract those tests exercise. Mechanical enforcement — a lint rule, a boundary check, a pre-commit guard — follows the target repository's existing tooling.