api-design-and-evolution
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAPI Design And Evolution
API 设计与演进
Design an interface as a durable agreement with its consumers, not a route list.
Start with the consumer job, domain meaning, authority boundary, and failure modes;
then choose the interface style and contract format. Keep facts, assumptions, and
policy decisions distinguishable.
将 interface 设计为与其 consumers 之间的持久 agreement，而不是一份 route list。
从 consumer job、domain meaning、authority boundary 和 failure modes 开始；
然后选择 interface style 和 contract format。始终明确区分 facts、assumptions 和
policy decisions。
When to use
何时使用
Use for a new or changed REST/HTTP API, GraphQL schema, RPC operation, event or
message contract, webhook, or streaming interface. Use it before implementation and
again whenever consumer-visible behavior changes.
适用于新的或发生变更的 REST/HTTP API、GraphQL schema、RPC operation、event 或
message contract、webhook 或 streaming interface。应在 implementation 之前使用，
并在每次 consumer-visible behavior 发生变化时再次使用。
When not to use
何时不使用
Do not use this as an ADR template, a complete product-discovery method, a security
assessment, or an implementation test plan. Hand those concerns to
adr-authoring,
product-discovery,
secure-software-engineering, and
verification-methodology, respectively.
不要将本 skill 用作 ADR 模板、完整的 product-discovery 方法、security
assessment 或 implementation test plan。请将这些关注点分别交给
adr-authoring、
product-discovery、
secure-software-engineering 和
verification-methodology。
Workflow
工作流
- Classify the scope. If the request spans more than one interface, start templates/api-landscape-assessment.md and read references/api-landscape-and-governance.md. If it changes where traffic is admitted, routed, observed, or isolated, read references/api-infrastructure-topologies.md. Keep portfolio findings separate from any individual contract decision.
- Discover the agreement. State consumer jobs, domain terms and invariants, authoritative data and schema owners, actors, object/action authority boundaries, data sensitivity, and failure modes. Record unanswered questions rather than inventing policy. Start templates/api-design-brief.md.
- Choose the interface shape. Compare interaction direction, coupling, delivery needs, query flexibility, mutation semantics, caching, observability, and evolution surface. Read references/interface-selection.md. Record the choice and rejected options in the brief; use an ADR only when the choice is consequential beyond this interface.
- Make the contract explicit. Define representations and their semantics, including null versus absent, defaults, enums/unions, identifiers, timestamps, units, ordering, filtering, and pagination. Use templates/endpoint-contract.md with references/contract-semantics.md.
- Design mutation and failure behavior. Define authority checks, preconditions, idempotency scope and equivalence, retries, concurrency, partial outcomes, long-running operation state, errors, and resource limits. Read references/operations-and-failures.md and create templates/error-taxonomy.md when errors are shared across operations.
- Describe asynchronous delivery where relevant. For messages, webhooks, or streams, state the publisher/subscriber perspective, envelope, delivery contract, duplicate/gap/reordering behavior, ordering scope, and security boundary. Read references/events-webhooks-streaming.md.
- Assess change from each consumer's perspective. Inventory consumers, generated clients, strict decoders, signatures, caches, quotas, and operational dependencies. Complete templates/compatibility-change-assessment.md. Do not call a change safe solely because it is additive.
- Plan and verify rollout. For a deprecation or migration, use templates/deprecation-migration-plan.md and references/evolution-and-deprecation.md. Review the contract using templates/contract-review.md. Test provider conformance, consumer expectations, compatibility diffs, examples, negative cases, and the deployed boundary. Load release-engineering for release sequencing, artifact promotion, progressive exposure, and coordinated rollback after the compatibility policy is defined.
- 确定 scope。 如果请求跨越多个 interface，请从 templates/api-landscape-assessment.md 开始，并 阅读 references/api-landscape-and-governance.md。 如果变更会影响 traffic 在何处被接纳、路由、观测或隔离，请阅读 references/api-infrastructure-topologies.md。 将 portfolio findings 与任何 individual contract decision 分开。
- 明确 agreement。 陈述 consumer jobs、domain terms 和 invariants、 authoritative data 和 schema owners、actors、object/action authority boundaries、 data sensitivity 和 failure modes。记录未解决的问题，而不是臆造 policy。请从 templates/api-design-brief.md 开始。
- 选择 interface shape。 比较 interaction direction、coupling、 delivery needs、query flexibility、mutation semantics、caching、observability 和 evolution surface。阅读 references/interface-selection.md。 在 brief 中记录所选方案与被否决的选项；仅当该选择的影响超出此 interface 时， 才使用 ADR。
- 明确 contract。 定义 representations 及其 semantics，包括 null 与 absent 的 区别、defaults、enums/unions、identifiers、timestamps、units、ordering、 filtering 和 pagination。使用 templates/endpoint-contract.md 和 references/contract-semantics.md。
- 设计 mutation 和 failure behavior。 定义 authority checks、preconditions、 idempotency scope 和 equivalence、retries、concurrency、partial outcomes、 long-running operation state、errors 以及 resource limits。阅读 references/operations-and-failures.md， 当 errors 在多个 operations 之间共享时，创建 templates/error-taxonomy.md。
- 在相关时描述异步 delivery。 对于 messages、webhooks 或 streams，说明 publisher/subscriber perspective、envelope、delivery contract、 duplicate/gap/reordering behavior、ordering scope 和 security boundary。阅读 references/events-webhooks-streaming.md。
- 从每个 consumer 的 perspective 评估 change。 盘点 consumers、 generated clients、strict decoders、signatures、caches、quotas 和 operational dependencies。完成 templates/compatibility-change-assessment.md。 不要仅因为某项 change 是 additive 就认定其安全。
- 规划并验证 rollout。 对于 deprecation 或 migration，使用 templates/deprecation-migration-plan.md 并阅读 references/evolution-and-deprecation.md。 使用 templates/contract-review.md 评审 contract。 测试 provider conformance、consumer expectations、compatibility diffs、examples、 negative cases 和 deployed boundary。在 compatibility policy 定义完成后，加载 release-engineering，以处理 release sequencing、 artifact promotion、progressive exposure 和 coordinated rollback。
Reference Guide
参考指南
| Load when | File |
|---|---|
| Assessing an API portfolio, ownership, duplication, discoverability, lifecycle, standards, or retirement | references/api-landscape-and-governance.md and templates/api-landscape-assessment.md |
| Comparing gateways, ingress proxies, service meshes, traffic direction, routing, policy, telemetry, or failure boundaries | references/api-infrastructure-topologies.md |
| Selecting REST/HTTP, GraphQL, RPC, event/message, webhook, or streaming | references/interface-selection.md |
| Modeling data, collection reads, schemas, or OpenAPI | references/contract-semantics.md |
| Designing writes, errors, retry behavior, limits, or authorization handoff | references/operations-and-failures.md |
| Designing event contracts, webhook delivery, or streams | references/events-webhooks-streaming.md |
| Reviewing compatibility, versions, deprecation, migration, or rollback | references/evolution-and-deprecation.md |
| Preparing contract/provider/consumer/deployment verification | references/contract-verification.md |
| Checking exact sources, versions, status, and intended use | references/source-index.md |
| Exercising required edge cases before claiming readiness | references/scenario-probes.md |
| 何时加载 | 文件 |
|---|---|
| 评估 API portfolio、ownership、duplication、discoverability、lifecycle、standards 或 retirement | references/api-landscape-and-governance.md 和 templates/api-landscape-assessment.md |
| 比较 gateways、ingress proxies、service meshes、traffic direction、routing、policy、telemetry 或 failure boundaries | references/api-infrastructure-topologies.md |
| 选择 REST/HTTP、GraphQL、RPC、event/message、webhook 或 streaming | references/interface-selection.md |
| 对 data、collection reads、schemas 或 OpenAPI 进行建模 | references/contract-semantics.md |
| 设计 writes、errors、retry behavior、limits 或 authorization handoff | references/operations-and-failures.md |
| 设计 event contracts、webhook delivery 或 streams | references/events-webhooks-streaming.md |
| 评审 compatibility、versions、deprecation、migration 或 rollback | references/evolution-and-deprecation.md |
| 准备 contract/provider/consumer/deployment verification | references/contract-verification.md |
| 核对 exact sources、versions、status 和 intended use | references/source-index.md |
| 在声明 readiness 前执行 required edge cases | references/scenario-probes.md |
Security Boundary
安全边界
Document authentication requirements and server-side object/action authorization in
the interface contract. For the threat model, credential handling, tenant isolation,
untrusted URLs or files, webhook signature design, output minimization, redaction,
or abuse resistance, load
secure-software-engineering. An API
contract cannot prove that an authorization boundary is enforced.
在 interface contract 中记录 authentication requirements 和 server-side
object/action authorization。对于 threat model、credential handling、tenant isolation、
untrusted URLs or files、webhook signature design、output minimization、redaction
或 abuse resistance，加载
secure-software-engineering。API
contract 无法证明 authorization boundary 已得到 enforced。
Ownership Boundaries
所有权边界
- Product owners decide consumer outcomes, audience, value, and lifecycle intent; this skill turns those decisions into interface agreements and evidence.
- Platform owners decide gateway, ingress, mesh, networking, deployment, and runtime operations. This skill identifies topology responsibilities and contract consequences but does not operate the substrate.
- Security owners decide threat models, credential and secret controls, abuse resistance, and tenant isolation. This skill records the contract handoff and required authorization behavior without substituting for the assessment.
- Architecture owners decide cross-system principles, significant boundaries, and durable architecture decisions. Use adr-authoring when a landscape or topology decision has consequences beyond the API portfolio.
An API landscape assessment is not a product roadmap, platform runbook, security
review, or enterprise architecture repository. Escalate unresolved ownership,
authority, or retirement decisions instead of assigning them implicitly.
- Product owners 决定 consumer outcomes、audience、value 和 lifecycle intent； 本 skill 将这些决策转化为 interface agreements 和 evidence。
- Platform owners 决定 gateway、ingress、mesh、networking、deployment 和 runtime operations。本 skill 会识别 topology responsibilities 和 contract consequences， 但不会操作 substrate。
- Security owners 决定 threat models、credential and secret controls、abuse resistance 和 tenant isolation。本 skill 记录 contract handoff 和 required authorization behavior，但不会取代该 assessment。
- Architecture owners 决定 cross-system principles、significant boundaries 和 durable architecture decisions。当 landscape 或 topology decision 的影响超出 API portfolio 时，使用 adr-authoring。
API landscape assessment 不是 product roadmap、platform runbook、security
review 或 enterprise architecture repository。对于尚未解决的 ownership、
authority 或 retirement decisions，应升级处理，而不是隐式地分配这些决定。
Completion
完成标准
Stop when the selected interface has an owner, an authoritative contract, explicit
consumer and failure assumptions, a compatibility assessment for each change, and
evidence or an explicit gap for each required review item. Escalate unresolved domain
semantics, authority, delivery, or consumer-impact questions to their accountable
owner.
当所选 interface 已有 owner、authoritative contract、明确的 consumer 和 failure assumptions、针对每项 change 的 compatibility assessment，并且每项 required review item 都有 evidence 或明确 gap 时，即可停止。将尚未解决的 domain semantics、authority、delivery 或 consumer-impact questions 升级处理，并提交给其 accountable owner。