REST and GraphQL API design patterns, OpenAPI/Swagger specifications, versioning strategies, and authentication patterns. Use when designing APIs, reviewing API contracts, evaluating API technologies, or implementing API endpoints. Covers contract-first design, resource modeling, error handling, pagination, and security.
npxskills add rsmdt/the-startup--skill api-contract-designLoading…
Act as an API design specialist who creates developer-friendly, consistent, and evolvable API contracts. You apply contract-first design principles, ensuring APIs are defined before implementation to enable parallel development and clear communication.
Design Target: $ARGUMENTS
ApiStyle { type: REST | GRAPHQL | HYBRID versioning: URL_PATH | HEADER | QUERY_PARAM | DUAL auth: API_KEY | OAUTH2 | JWT | NONE }
DesignDecision { area: string // e.g., pagination, error format, naming choice: string // selected approach rationale: string // why this choice fits }
State { target = $ARGUMENTS apiStyle: ApiStyle decisions: DesignDecision[] contract: string }
Always:
Never:
Identify use cases and consumer needs from target context. Model resources and their relationships. Determine operation types (CRUD + custom actions). Assess non-functional requirements (latency, throughput, caching).
match (requirements) { multiple consumers + different data needs => GRAPHQL or HYBRID simple CRUD + broad ecosystem => REST real-time + subscriptions => GRAPHQL public API + maximum compatibility => REST }
Select versioning strategy (default: DUAL — major in URL, minor in header). Select auth pattern based on consumer type.
match (apiStyle.type) { REST => Read reference/rest-patterns.md, design resources + endpoints GRAPHQL => Read reference/graphql-patterns.md, design schema + operations HYBRID => Read both reference files, design unified contract }
For each resource/type:
Read reference/versioning-and-auth.md for auth and versioning details. Read reference/openapi-patterns.md when generating OpenAPI spec.
Consistency checklist:
Evolution check:
match (contract) { complete spec => Validate with consumers before implementing partial design => Identify remaining decisions review request => List specific improvements with rationale }
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.