接口与协议
rest-api-design-documentation
更新于 2026-08-24
REST API · 文档规则
Documentation rules for REST API: decision-level content, tested examples and versioned guides.
- 技术栈
- REST API
- 主题
- 文档
- 条目
- 9 条
- 版本
- v0.2.0
✓ 应当这么做
- ✓ Document decisions and invariants, not restatements of the code
- ✓ Keep runnable examples in the docs and test them in CI
- ✓ Date and version external-facing documents
✕ 常见反模式
- ✕ Copy-pasted README sections that drift from the code
- ✕ Docs without an owner
- ✕ Silently dropping deprecated configuration from the guide
◎ 交付前验证
- ◎ Integration tests cover the success and the failure branch of each new route
- ◎ No unhandled promise rejection warnings in the test output
- ◎ Graceful shutdown drains in-flight requests
同分类条目
13 篇接口与协议
REST API 工程规则
REST design rules: resource naming, idempotent verbs and typed error envelopes
接口与协议
OpenAPI Contract 工程规则
OpenAPI rules: spec-first changes and generated client parity in CI
接口与协议
WebSocket 工程规则
WebSocket rules: authenticated handshake, heartbeat and backpressure
接口与协议
SSE Streaming 工程规则
SSE rules: bounded event size, heartbeat comments and reconnect semantics
接口与协议
Rate Limiting 工程规则
Rate limit rules: per-principal quotas and explicit 429 semantics