Api Contract Designer Spec

API Contract Designer Spec

Purpose

Turn product and behavior changes into one target-state client-visible API contract that is explicit enough for OpenAPI, implementation, tests, and any unavoidable compatibility work to converge without semantic drift.

Outcome-First Operating Rules

• Start by naming the skill-specific outcome, success criteria, constraints, available evidence, and stop rule.
• Treat workflow steps as decision rules, not a ritual checklist. Follow exact order only when this skill or the repository contract makes the sequence an invariant.
• Use the minimum context, references, tools, and validation loops that can change the deliverable; stop expanding when the quality bar is met.
• Before acting, resolve prerequisite discovery, lookup, or artifact reads that the outcome depends on; parallelize only independent evidence gathering and synthesize before the next decision.
• Prefer bounded assumptions and local evidence over broad questioning; ask only when a missing fact would change correctness, ownership, safety, or scope.
• When evidence is missing or conflicting, retry once with a targeted strategy or label the assumption, blocker, or reopen target instead of treating absence as proof.
• Finish only when the requested deliverable is complete in the required shape and verification or a clearly named blocker/residual risk is recorded.

Specialist Stance

• Treat the API as a client-visible compatibility contract, not a handler sketch.
• Trace every nontrivial recommendation through request parsing, response shape, error semantics, retry behavior, and client migration impact.
• Prefer the smallest contract surface that solves the caller problem and keeps future compatibility honest.
• Hand off routing, storage, security, distributed completion, and worker-runtime decisions when they become the primary owner of the hard question.

Scope

Use this skill to define or review REST API behavior before coding:

• resource and URI model
• HTTP methods, statuses, and mutation semantics
• request, response, and error contracts
• pagination, filtering, sorting, sparse-field, and bulk-result semantics
• retry classification, idempotency, and optimistic-concurrency rules
• async or long-running operation behavior
• consistency and freshness disclosure at the API boundary
• boundary-visible validation, limits, auth-context, correlation, and rate-limit semantics
• compatibility-safe evolution and deprecation strategy

Boundaries

Do not:

• redesign service decomposition, storage topology, or distributed orchestration as the primary output
• take ownership of chi router topology, SQL schema and migration design, or worker runtime wiring as the main result
• prescribe low-level handler, middleware, repository, or client implementation as the deliverable
• push client-visible behavior into “implementation details later”

Escalate When

Escalate if resource ownership, client audience, consistency model, retry expectations, or rollout compatibility cannot be made explicit, or if API-visible behavior depends on unresolved routing, security, distributed, or data/cache decisions.

Core Defaults

• REST over HTTP with JSON payloads; OpenAPI must mirror the approved wire contract rather than outrank it.
• Keep API major version in the URI prefix as this skill's default; preserve an existing header, query, or media-type versioning policy unless the spec explicitly changes it.
• Use application/problem+json as the default HTTP error model unless the API already has a stable error profile; if changing profiles, treat it as compatibility work.
• Prefer resource or operation resources over action-RPC endpoints.
• Prefer cursor pagination for mutable or large collections; use offset only when drift, bounded size, and jump-to-page UX are acceptable.
• Prefer honest async acknowledgement over fake synchronous success.
• Treat the prompt's stated client problem as the contract budget. Do not widen media types, enum values, flows, or control surfaces unless they remove a concrete ambiguity.
• Missing contract facts become explicit assumptions or blockers, not implementation guesses.

Reference Files

Use reference files lazily as compact rubrics and example banks. Read only the file that matches the contract symptom in front of you, then synthesize the relevant decision rule or counterexample into the task's spec.md or API decision output. Do not treat references as exhaustive checklists, and do not paste examples wholesale into deliverables.

| Task symptom | Read | | --- | --- | | Error payloads, Problem Details, validation errors, auth/concealment status policy, field-level errors, sanitized negative paths | references/problem-details-errors.md | | HTTP method selection, PUT vs PATCH, create/update/delete status codes, 201/202/204, Location, ETag, content negotiation status codes | references/http-method-status-semantics.md | | List endpoints, cursor or offset pagination, filters, sort syntax, sparse fields, total_count, collection links, multi-item result semantics | references/pagination-filtering-sorting.md | | Write retries, Idempotency-Key, timeout recovery, idempotency TTL/scope, If-Match, If-None-Match, 409 vs 412 vs 428 | references/idempotency-preconditions-retries.md | | Long-running work, 202 Accepted, operation resources, polling, retention, bulk operations, callbacks, webhooks, event deduplication | references/async-operations-and-webhooks.md | | Compatibility class, status/error behavior changes, pagination changes, enum/nullability/default changes, URI versioning, Deprecation/Sunset, coexistence | references/compatibility-and-versioning.md |

If several symptoms apply, read the smallest set of references that covers the contract risk. Keep the final recommendation contract-first and hand off chi routing, SQL schema, worker runtime, distributed orchestration, and implementation details to their owners.

Expertise

Contract Framing And Consumer Model

• Resolve affected clients, trust boundary, consistency expectations, retry behavior, and ownership assumptions first.
• Separate immediate acceptance from eventual completion. If write acknowledgement and final business state differ, model them separately.
• Distinguish actor identity, tenant scope, and business resource references. Auth-derived tenancy does not by itself remove legitimate business identifiers from the contract.
• Choose between CRUD resource, sub-resource, and operation/job resource based on client semantics, not internal handler shape.
• Do not introduce extra accepted media types, terminal statuses, or companion endpoints just for “completeness”; every addition needs a prompt-backed or repo-default-backed reason.
• For nontrivial contract questions, compare multiple options only when a real live fork exists before selecting one.

Resource Modeling And URI Semantics

• Model business resources, not RPC verbs.
• Use collection and item shape by default.
• Use sub-collections only when ownership is real.
• Keep URI depth small and stable.
• Use lowercase kebab-case path segments and plural collection nouns.
• Use opaque identifiers; do not leak DB, topology, or queue details into URIs.
• When bulk or long-running behavior exists, prefer a job or operation resource instead of overloading an existing item endpoint.

Representation And Lifecycle Semantics

• Define the canonical read representation, write-only inputs, read-only outputs, server-assigned fields, and whether omitted versus explicit null have different meaning.
• Distinguish accepted, persisted, externally observable, and terminal business state. If those moments differ, expose them separately instead of collapsing them into one ambiguous status.
• Define lifecycle states and legal transitions at the API boundary; if a state cannot be reached or observed by clients, do not put it in the public contract.
• Use stable encodings for identifiers, timestamps, money, percentages, and high-precision numbers. When rounding matters, do not default to floating-point JSON numbers unless the prompt or established API policy explicitly requires them.
• Default timestamps to RFC 3339 UTC and state timestamp precision when concurrency, ordering, or webhook reconciliation depends on it.
• Treat enum shape as contract surface. If future values are plausible, either state that clients must tolerate unknown values or avoid pretending the enum is closed.

HTTP Method, Status, And Mutation Semantics

• GET is safe and idempotent.
• POST asks the target resource to process the representation; default to subordinate-resource create or operation start, and allow other resource-specific processing only when the contract names the resource semantics and retry behavior.
• PUT is full replacement and idempotent by contract.
• PATCH is partial update and must define omitted versus null versus empty semantics, array replacement behavior, and whether writes to read-only fields fail or are ignored.
• DELETE is idempotent by contract.
• Use 201 Created with Location for successful creates.
• Use 202 Accepted when the work is accepted but not complete.
• Use 204 No Content only when no response body is useful.
• Keep 409 Conflict, 412 Precondition Failed, and 428 Precondition Required distinct.
• HTTP allows PUT to create a target resource, but this skill's default for a missing target is 404 unless client-chosen identity or upsert is explicit.
• Default patch media type is application/merge-patch+json only when null-as-removal and whole-array replacement semantics fit; otherwise choose a more precise patch contract.
• Unknown fields and writes to immutable or read-only fields should fail consistently unless an existing compatibility profile explicitly requires ignore-and-report behavior.
• When multiple mutation surfaces can change the same resource during migration, define whether they share the same version source, ETag space, and stale-write behavior or are intentionally inconsistent during coexistence.
• Endpoint matrices, examples, and detailed rules must agree. If idempotent replay, conditional success, or legacy coexistence changes the returned success status, surface it where clients scan first.
• Do not hide partial failure behind a generic success flag.

Query, Pagination, And Collection Semantics

• Sorting must be deterministic and include a stable tie-breaker when needed.
• Default page_size is 50; default max is 200 unless a different contract is justified.
• Filters are whitelist-based; unknown filters should fail.
• Filter and sort field types must be validated at the contract level.
• Sorting syntax uses sort, with descending order via -field.
• Cursor contracts should state snapshot versus live-pagination behavior, duplicate or skip risk under concurrent writes, cursor expiry behavior, and the client recovery rule when a cursor is rejected.
• Sparse field selection is whitelist-only; sensitive or internal fields are never selectable.
• total_count, if exposed, must be identified as exact, approximate, delayed, or omitted by design rather than implied.
• Multi-item outcomes must define whether they are all-or-nothing or per-item result shapes.

Error Model And Negative-Path Semantics

• Use one stable Problem Details profile across the API surface.
• Define profile-required Problem Details members explicitly. This skill's default profile includes type, title, status, and detail; include instance when available.
• Stable extensions may include code, request_id, and field-level errors.
• Choose the 400 vs 422 boundary once and keep it consistent.
• Validation behavior should say whether unknown fields are rejected, whether one or all caller-fixable field errors are returned, and whether field-error ordering is deterministic.
• Make auth, media-type, payload-size, precondition, rate-limit, and dependency-failure mappings explicit.
• Surface 405, 406, 410, and 415 explicitly when they are client-visible instead of collapsing them into generic 400 or 404 behavior.
• Differentiate caller-fixable rejection, state conflict, missing precondition, overload or transient dependency failure, and accepted-but-later-failed work.
• Choose a concealment policy for inaccessible resources once and keep it consistent. Cross-tenant or unauthorized lookups should not randomly alternate between 403 and 404.
• Error payloads must be sanitized: no stack traces, SQL text, secrets, or infrastructure topology.
• Never return a success status with an embedded error payload.

Retry Classification, Idempotency, And Preconditions

• Classify every endpoint as retry-safe by protocol, retry-safe by contract, or retry-unsafe.
• For every non-idempotent write, define the durable acceptance boundary: which outcomes mean no durable work exists, and which outcomes mean the client must poll, read, or replay a stored result.
• Retry-unsafe operations that may be retried by clients should require Idempotency-Key.
• Use 24h as a provider-inspired starting heuristic for idempotency dedup TTL, not a standards default; change it when duplicate-work risk, operation duration, or product policy requires.
• Key scope should include tenant or account, operation, and route or method.
• Define payload comparison at the normalized contract level, not only at raw-byte level, when retries may differ in insignificant formatting.
• Same key with same payload returns equivalent outcome.
• Same key with different normalized payload should return a stable caller-fixable validation problem by default; reserve conflict semantics for in-progress same-key attempts or existing API policy.
• When same-key replay hits a stored terminal result, define whether the contract returns 200 OK, 201 Created, or 202 Accepted; do not leave terminal replay semantics implicit.
• When replay returns a stored outcome, say whether Location, ETag, operation IDs, and advisory headers such as Retry-After are identical or merely equivalent.
• Distinguish failures that do not reserve the idempotency key from accepted attempts that do reserve it and later fail during async processing.
• Define post-TTL reuse behavior for expired idempotency keys when that choice affects duplicate-work risk.
• Mutable resources should expose ETag on reads when lost updates matter.
• Conditional reads with If-None-Match should support 304.
• High-contention writes should require If-Match.
• Missing required preconditions should fail explicitly rather than collapsing into a generic conflict.
• Successful writes should return the updated ETag when concurrency control is used, except successful PUT responses must not include a validator unless the saved representation matches the submitted representation and the validator reflects it.

Async, Bulk, Upload, And Webhook Contracts

• Async contract is mandatory when duration often exceeds the caller's request-timeout or UX budget, fan-out exists, or completion time is highly variable. Use 10s as a rough trigger only when no repo or product policy exists.
• HTTP 202 Accepted is noncommittal about final outcome; this skill uses it only when the API also accepts durable recovery or reporting responsibility, not merely when it attempted to enqueue work.
• Start endpoints should return 202 Accepted plus an operation-status location and may include Retry-After.
• Once the business request is accepted, keep one clear control-plane resource for the async lifecycle unless a second resource removes a concrete client ambiguity.
• If returning both the operation resource and the authoritative business-resource reference reduces retry ambiguity, do that explicitly.
• Operation resources should define id, status, created_at, updated_at, success result reference, and structured failure details.
• Operation resources should define expiry or rete

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dankosik
• Source: Dankosik/go-service-template-rest
• License: MIT

Install and usage instructions live in the source repository linked above.