api-and-interface-design
Designs or reviews HTTP, REST, GraphQL, RPC, CLI, webhook, event, and service interfaces with explicit inputs, outputs, errors, compatibility, idempotency, pagination, authentication, versioning, and observability. Use when introducing or changing an API or cross-component contract. Not for internal implementation details with no boundary or for debugging one API failure; use root-cause-debugging there.
thiientv · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thiientv/godmode --skill api-and-interface-design技能说明
name: api-and-interface-design description: >- Designs or reviews HTTP, REST, GraphQL, RPC, CLI, webhook, event, and service interfaces with explicit inputs, outputs, errors, compatibility, idempotency, pagination, authentication, versioning, and observability. Use when introducing or changing an API or cross-component contract. Not for internal implementation details with no boundary or for debugging one API failure; use root-cause-debugging there.
API and Interface Design
Design the contract from the caller's failure modes, not only the happy path.
Establish the contract
- Identify consumers, trust boundaries, lifecycle, latency expectations, and ownership.
- Define request/command shape, response/event shape, status or error model, validation, defaults, and canonical examples.
- Decide idempotency, retries, ordering, pagination, concurrency, rate limits, cancellation, and partial failure behavior.
- Define authentication, authorization, sensitive fields, and audit needs.
- Decide compatibility and versioning: additive change, migration, deprecation, or explicit breaking release.
Read contract-checklist.md for the review matrix. Keep the contract close to the owning schema or source of truth and generate clients/docs only when the repository already supports generation.
Implementation handoff
Write examples that can become contract tests. Include malformed input, missing resource, duplicate request, timeout, dependency failure, permission denial, and oversized input cases. Make error codes stable enough for callers and messages safe enough for logs and users.
Do not expose internal stack traces, persistence identifiers, or implementation details by accident. Do not add versioning machinery before a compatibility need exists.
Completion condition
Consumers can predict valid requests, successful and failed responses, retry behavior, compatibility impact, and the evidence that proves the boundary.