# Api Contract Designer Spec > Design API-contract-first specifications for Go services. Use when planning or revising client-visible REST API behavior before coding and you need explicit resource modeling, HTTP method/status semantics, request/response/error contracts, pagination/filter semantics, idempotency/retry/concurrency rules, async behavior, consistency disclosure, and compatibility-safe evolution. Skip when the task… - **Type:** Skill - **Install:** `agentstack add skill-dankosik-go-service-template-rest-api-contract-designer-spec` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Dankosik](https://agentstack.voostack.com/s/dankosik) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Dankosik](https://github.com/Dankosik) - **Source:** https://github.com/Dankosik/go-service-template-rest/tree/main/.agents/skills/api-contract-designer-spec ## Install ```sh agentstack add skill-dankosik-go-service-template-rest-api-contract-designer-spec ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://github.com/Dankosik) - **Source:** [Dankosik/go-service-template-rest](https://github.com/Dankosik/go-service-template-rest) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-dankosik-go-service-template-rest-api-contract-designer-spec - Seller: https://agentstack.voostack.com/s/dankosik - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.