HTTP API
Design and review HTTP-facing APIs (usually JSON): predictable URLs, honest status codes, and errors clients can build on—without duplicating everything your api-compat skill covers for long-lived versioning policy.
Scope
- - Modeling: nouns/resources, collections, actions when RPC-style is clearer than fake REST.
- HTTP semantics: which methods, idempotency, caching headers when relevant.
- Errors: stable machine-readable codes, correlation ids, avoid leaking internals.
- DX: examples, OpenAPI snippets, consistent pagination/filter patterns.
Out of scope (hand off)
- - OAuth/OIDC protocol details → identity-focused skills.
- GraphQL-only schema design → graphql-schema skill.
- Multi-year deprecation policy and client migration programs → pair with api-compat.
Review order
- 1. Read paths — Can a client navigate the domain without guessing?
- Write safety — Retries safe? Duplicate submits handled?
- Errors — One shape everywhere; 4xx vs 5xx honest.
- Evolution — Document what may change vs what is stable (compat details in api-compat).
Smells
- - Status 200 with
{error: ...}; every POST returns 200; unbounded list endpoints; secrets in error bodies.
Done when
- - A new engineer can call the API from docs alone; failure cases are testable and consistent.
HTTP API
设计和审查面向HTTP的API（通常为JSON）：可预测的URL、诚实的状态码以及客户端可依赖的错误信息——无需重复您在api-compat技能中涵盖的长期版本控制策略。
范围
- - 建模：名词/资源、集合、当RPC风格比虚假REST更清晰时的操作。
- HTTP语义：使用哪些方法、幂等性、相关时的缓存头。
- 错误：稳定的机器可读代码、关联ID、避免泄露内部信息。
- 开发者体验：示例、OpenAPI片段、一致的分页/过滤模式。
不涉及范围（移交处理）
- - OAuth/OIDC协议细节 → 交由身份相关技能处理。
- 仅GraphQL模式设计 → 交由graphql-schema技能处理。
- 多年弃用策略和客户端迁移计划 → 与api-compat配合处理。
审查顺序
- 1. 读取路径 — 客户端能否无需猜测即可导航领域？
- 写入安全性 — 重试是否安全？重复提交是否已处理？
- 错误 — 统一格式；4xx与5xx状态码诚实区分。
- 演进 — 记录可能变化的内容与稳定内容（兼容性细节见api-compat）。
不良信号
- - 状态码200返回{error: ...}；每个POST都返回200；无限制的列表端点；错误体中包含机密信息。
完成标准
- - 新工程师仅凭文档即可调用API；失败案例可测试且一致。
