api-design
REST conventions for status codes, pagination, errors, versioning, and idempotency. Use when designing or reviewing HTTP APIs.
- License 许可
- MIT
- 最近更新
- 2026-10-20
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- api-design
- license
- MIT
- description
- REST conventions for status codes, pagination, errors, versioning, and idempotency. Use when designing or reviewing HTTP APIs.
- compatibility
- opencode
03 SKILL.md 正文
What I do
- Keep every endpoint predictable: same status semantics, same paging, same error shape.
When to use me
Use when designing or reviewing HTTP APIs.
Rules
- Status codes: 200 read/update, 201 create (with resource location), 400 validation, 401 unauthenticated, 403 unauthorized, 404 unknown resource, 409 conflict, 422 semantically invalid, 500 server fault. No 200-with-error-body.
- Errors: one shape everywhere — machine-readable
code, humanmessage, per-fielddetailsfor validation failures. - Pagination: cursor-based with
limitcap; envelope{ data, nextCursor }. Never unbounded lists. - Versioning: version in path (
/v1/...) from day one; never break a shipped contract — add, don't alter. - Idempotency: state-changing POSTs accept
Idempotency-Key; retries with the same key return the original result. - Methods: GET never mutates; PUT full replace, PATCH partial; DELETE idempotent.
04 同仓库更多 Skills
demo-skill
暂无简介
web-accessibility
WCAG 2.2 AA practice for keyboard, screen reader, contrast, and motion. Use when building or auditing user interfaces.
ui-conventions
Black/white token system, accessible components, and copy rules for frontend work. Use when building screens, components, or design tokens.
test-evidence
stack-toolchain test matrices, concurrency cases, and TASK_PROGRESS proof format for QA verification. Use when writing tests or proving deliverables work.
test-driven-development
RED-GREEN-REFACTOR cycle for new behavior. Use when implementing any feature, fix, or endpoint before writing production code.
systematic-debugging
Reproduce-isolate-fix-verify loop for defects and flaky behavior. Use when facing a bug, test failure, or unexpected behavior.