资源 · 33

在不流失客户端的情况下改进 API 合约。

描述请求、响应和错误;测试版本并确保 Webhook 可安全重放。

已更新 · 17 min

虚构的无人API验证工作台,配有网络网关、抽象请求与响应图、酒红色文件夹及黄铜台灯 由人工智能生成的编辑插图

本指南有助于实现的目标

  • 编写合同
  • 澄清错误
  • 测试兼容性
  • 规划停用

快速检查

  • 哪些客户端使用每个操作?
  • 错误类型是否稳定且状态一致?
  • 旧客户端能否容忍此变更?
  • 重试是否会重复操作?
  • 如何宣布和验证停用?

分步指南

  1. 1

    清点使用者

    列出操作、客户端、使用情况、版本和所有者。 在更改字段之前,将观察到的使用情况与假设区分开来。

    交付成果:合同依赖关系图。

  2. 2

    描述请求和响应

    维护包含模式、实际示例、成功和失败响应的 OpenAPI 描述。 针对正在运行的服务进行检查。

    交付成果:版本化的契约和一致性测试。

  3. 3

    稳定错误

    根据语义使用 HTTP 状态,并在必要时使用 RFC 9457 中记录的问题类型。不要泄露敏感信息的细节。

    交付成果:已测试的错误目录。

  4. 4

    对变更进行分类

    检查必填字段、类型、值、行为、超时和分页。 使用代表性案例测试旧客户端与新版本的兼容性。

    交付成果:兼容性矩阵和版本决策。

  5. 5

    增强通知的健壮性

    对于 Webhook,规划身份验证、无序传递、重复和重试机制。 在可能重复的情况下,确保处理过程的幂等性。

    交付成果:重放和确认场景。

  6. 6

    发布版本,并提供退出路径

    发布迁移说明、共存期和联系方式。 统计旧版本使用情况,并在确认受影响用户后方可停用。

    交付成果:迁移计划和停用证明。

管理指标

指标衡量内容首要行动
合同操作描述及与服务行为的匹配修复差异
兼容性变更前对代表性客户端进行测试添加缺失案例
错误记录不包含敏感数据的类型修改消息和模式
迁移允许使用旧版本并指定所有者协助剩余客户端

常见错误

  • 假设仅版本号即可保持兼容性
  • 仅记录 200 个响应
  • 在错误中返回内部跟踪或密钥
  • 假设 Webhook 仅按顺序到达一次

常见问题解答

OpenAPI 是否取代测试?

否。将描述与实际响应和用户需求进行比较。

每次变更都需要新版本吗?

否。根据客户端影响和合同行为来决定; 不兼容的变更需要明确的计划。

为什么需要输入错误?

它们为客户提供了一种稳定的方式来区分问题并选择相应的操作。

ETag、HTTP 缓存与并发更新

此语言版本的详细参考说明以英语提供。

Two clients, three versions: make a conflict visible

In this fictional scenario A and B edit the same representation. The server emits a strong ETag for each newly stored version. If-Match rejects a modification based on a version that is no longer current. These five explanatory excerpts make no connection and perform no real write.

1. A reads the initial version

A receives representation v1 and keeps "v1" with the data being edited. A copied tag without its representation is insufficient to understand a conflict.

Request excerpt

GET /demo/resource HTTP/1.1
Host: api.example.test

Response excerpt

HTTP/1.1 200 OK
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store
ETag: "v1"
2. B saves before A

B has also read v1. Its PUT satisfies If-Match: "v1". The exact new representation is stored as "v2"; this server returns 204 with the new validator.

Request excerpt

PUT /demo/resource HTTP/1.1
Host: api.example.test
If-Match: "v1"

Response excerpt

HTTP/1.1 204 No Content
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store
ETag: "v2"
3. A attempts a stale write

The current version is now v2. A still sends If-Match: "v1": 412, without applying its modification. Preserve local work for comparison.

Request excerpt

PUT /demo/resource HTTP/1.1
Host: api.example.test
If-Match: "v1"

Response excerpt

HTTP/1.1 412 Precondition Failed
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store
4. A reads again and resolves the conflict

A retrieves v2 and compares its original data, local edits and the current version. A person or an explicit business rule chooses which changes to retain.

Request excerpt

GET /demo/resource HTTP/1.1
Host: api.example.test

Response excerpt

HTTP/1.1 200 OK
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store
ETag: "v2"
5. A submits a reconciled modification

After that decision, A sends the revised proposal with If-Match: "v2". It succeeds in this scenario and creates v3. Another concurrent writer could still require another cycle.

Request excerpt

PUT /demo/resource HTTP/1.1
Host: api.example.test
If-Match: "v2"

Response excerpt

HTTP/1.1 204 No Content
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store
ETag: "v3"

Fictional HTTP/1.1 excerpts: request and response bodies are omitted even where allowed. HEAD, 204 and 304 have no response content. The api.example.test domain and fixed date serve only to explain this scenario.

The protocol detects a stale version; it does not decide how to merge content. Document what the interface retains after 412, who resolves the conflict and when a fresh read is needed. If-Match: * does not replace comparison of a specific strong ETag.

Explore ETag comparisons and the simulator →

Primary references and limits

The standards define HTTP conditions and caching. The ten cases, laboratory and two-client walkthrough are original illustrations. Displayed results are calculated by this local model, not measurements of this site or your infrastructure.

References reviewed

Retry-After:等待、预算与重试决策

此语言版本的详细参考说明以英语提供。

Specify permission to repeat before retry timing

Retry-After describes waiting. The contract must also define replayable operations, keys, versions and unknown-result states.

  • State whether the field is seconds or a date and how clients handle absent or invalid values.
  • Name the retry controller and global budget to prevent overlapping attempts.
  • Retain parameters, context and the idempotency window without generalising Stripe to every API.

Explore Retry-After and the retry model →

References reviewed · RFC 9110 · §9.2.2, §10.2.3 · RFC 6585 · §4 · AWS

OAuth/OIDC:受众与权限

此语言版本的详细参考说明以英语提供。

An API contract must name its audience and permissions

Bind the route to an expected resource, explicit scopes and an object rule. Signature verification alone does not establish this contract.

  • Document accepted profiles and separate access tokens, ID tokens and opaque tokens.
  • Test a token intended for another API, missing scope and another tenant’s object.
  • Return a controlled denial and keep traces free of codes and tokens.

See token recipients and the ten OAuth/OIDC cases →

Sources reviewed on · IETF · RFC 9700 · OAuth 2.0 Security BCP · IETF · RFC 9068 · JWT access token profile · OpenID Foundation · OpenID Connect Core 1.0 · IETF · RFC 8725 · JWT Best Current Practices · IETF · RFC 6749 · OAuth 2.0 framework

Webhook:签名与重放

此语言版本的详细参考说明以英语提供。

The contract must define the exact authenticated bytes

Stripe and GitHub do not use the same HMAC message. Record the header, raw body, trusted keys and freshness policy without generalising one provider’s profile.

  • Test a reformatted body with its original signature.
  • Separate cryptographic validation, freshness and duplicate recognition.
  • Document durable acknowledgement and business status with distinct evidence.

See webhook signatures, digests and the ten cases →

Sources reviewed on · Stripe · Webhooks · Stripe · Manage webhook endpoints · GitHub · Validating webhook deliveries · GitHub · Best practices for using webhooks · GitHub · Handling failed webhook deliveries

API错误:类型、状态与证据

此语言版本的详细参考说明以英语提供。

A useful API error connects a stable problem type, an occurrence and a possible client action. RFC 9457, published in July 2023 to replace RFC 7807, supplies a common format. It does not turn an error message into authorisation evidence, replay instructions or a complete security diagnosis.

Five explained standard members, six problem types in the IANA snapshot updated 26 June 2026, and eight fictional acceptance cases. Sources consulted 23 October 2026. Examples and proposed tests are original CIE material.

IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5

Five members: role and client-side reading

Five members: role and client-side reading
MemberExpected typeRoleAcceptance question
typestring · URI referenceIdentifies the problem type; defaults to about:blank if absent.Does the client decide using the URI rather than a translated title?
statusnumber · HTTP statusRestates the status for this occurrence; advisory.Do body and response status agree?
titlestringHuman-readable summary of the problem type.Does localisation change only person-facing text?
detailstringHuman-readable explanation of this occurrence.Does the client avoid parsing prose as a machine code?
instancestring · URI referenceIdentifies a particular occurrence.Does the reference support follow-up without exposing internal details?

These members are optional. Consumers must ignore a member with an unexpected JSON type. They must also tolerate unrecognised extensions. The specified JSON media type is application/problem+json.

阅读练习

Select one of eight examples, then optionally change the assumed received HTTP status. The body and media type remain those of the chosen case. This workshop compares limited facts; it validates neither all URIs, business schemas, authorisation nor a real service. The media-type name is compared without validating all its parameters. HTTP method and other transport rules still need checking.

Only the fictional examples displayed below are used. URIs are shown as text: none is automatically visited or resolved. No production log or message is requested.

Six registered types: preserve exact URIs and references

This common-type registry is not a list of every problem an API can define. N/A for about:blank is not an HTTP status. The three digest entries retain a draft-kind reference as published in this IANA snapshot; this is not rewritten as a final RFC number.

IANA · HTTP Problem Types · Registry updated 2026-06-26 · consulted 2026-10-23

Six registered types: preserve exact URIs and references
Type URI and IANA titleRecommended statusReference as publishedRegistration date
about:blank

See HTTP Status Code

N/A

rfc · rfc9457

2023-05-02
https://iana.org/assignments/http-problem-types#date

Date Not Acceptable

400

rfc · rfc9458 · §6.5.2

2023-05-02
https://iana.org/assignments/http-problem-types#ohttp-key

Oblivious HTTP key configuration not acceptable

400

rfc · rfc9458 · §5.3

2023-05-02
https://iana.org/assignments/http-problem-types#digest-unsupported-algorithms

Unsupported Hashing Algorithms

400

draft · RFC-ietf-httpapi-digest-fields-problem-types-06 · §3.1

2026-06-26
https://iana.org/assignments/http-problem-types#digest-invalid-values

Invalid Digest Values

400

draft · RFC-ietf-httpapi-digest-fields-problem-types-06 · §3.2

2026-06-26
https://iana.org/assignments/http-problem-types#digest-mismatched-values

Mismatched Digest Values

400

draft · RFC-ietf-httpapi-digest-fields-problem-types-06 · §3.3

2026-06-26

IANA · Protocol Registries licensing · CC0 1.0 · Revised 2021-11-10 · CIE commentary and fictional examples identified separately

Eight cases and acceptance decisions

P01 · An explicit business problem type

HTTP 422 · Content-Type: application/problem+json

{
    "type": "https://api.example.net/problems/invalid-window",
    "title": "Invalid time window",
    "status": 422,
    "detail": "The end must follow the start.",
    "instance": "/problems/events/test-17",
    "errors": [
        {
            "field": "end",
            "code": "before-start"
        }
    ]
}

Reading : Body and response statuses agree. The errors array is an extension specific to this example, not a universal standard member.

Test to add : Test the stable before-start code and field association; do not parse detail prose to automate correction.

P02 · Type and status omitted

HTTP 404 · Content-Type: application/problem+json

{
    "title": "Ressource introuvable",
    "instance": "/support/test-18"
}

Reading : The five members are not an all-required checklist. Without a usable type, about:blank applies; the received HTTP status remains 404.

Test to add : Check that the client accepts this minimal response and a localised title without inventing a body status.

P03 · Body says 403 but HTTP says 200

HTTP 200 · Content-Type: application/problem+json

{
    "type": "https://api.example.net/problems/access-denied",
    "title": "Access denied",
    "status": 403
}

Reading : Two layers disagree. The advisory JSON status does not replace the status received by generic HTTP clients.

Test to add : Investigate generation and intermediaries; preserve both values rather than declare success from HTTP 200 alone.

P04 · Five members with the wrong JSON type

HTTP 422 · Content-Type: application/problem+json

{
    "type": 17,
    "title": false,
    "status": "422",
    "detail": [
        "Invalid"
    ],
    "instance": null,
    "traceRef": "test-19"
}

Reading : type, title, status, detail and instance have unexpected types. RFC consumer handling is to ignore them rather than coerce the string "422" into a number.

Test to add : Report the producer defect and test a tolerant client. traceRef remains an extension; about:blank is the default after type is ignored.

P05 · Relative URI and unknown extensions

HTTP 409 · Content-Type: application/problem+json

{
    "type": "/problems/conflict",
    "title": "Version conflict",
    "status": 409,
    "instance": "?case=test-20",
    "requestRef": "test-20",
    "retryable": false
}

Reading : The type uses a relative path and instance a query reference. This workshop displays them without resolution; the real document base would be required.

Test to add : Define the contract base, prefer an absolute type and test ignored unrecognised extensions. The word retryable alone does not grant universal replay safety.

P06 · An exact registered URI

HTTP 400 · Content-Type: application/problem+json

{
    "type": "https://iana.org/assignments/http-problem-types#date",
    "title": "Date Not Acceptable",
    "status": 400,
    "instance": "/support/test-21"
}

Reading : This type appears in the IANA snapshot. Its recommended status is 400. Comparing only #date or title does not identify the type.

Test to add : Refer the client to this type’s definition in its applicable context; registration does not certify an implementation.

P07 · A similar object with another media type

HTTP 503 · Content-Type: application/json

{
    "type": "https://api.example.net/problems/maintenance",
    "title": "Service maintenance",
    "status": 503,
    "detail": "Try the documented recovery path."
}

Reading : The body resembles Problem Details, but the received media-type name is application/json. Structural reading does not verify negotiation or the response contract.

Test to add : Compare Content-Type, documentation and client. This example is not a retry rule: Retry-After and replay safety remain separate checks.

P08 · A number is not sufficient for an HTTP status

HTTP 400 · Content-Type: application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 700,
    "instance": "/support/test-22"
}

Reading : status is a JSON number, but 700 lies outside the HTTP three-digit range 100–599. This differs from having the wrong JSON type.

Test to add : Repair generation and preserve the received HTTP status, 400 here. A data-type-only check would have missed this anomaly.

IETF · RFC 9110 · HTTP Semantics · June 2022 · §6.4.1, §15, §15.3.6 · status range and response content

Evolve an error without breaking its contract

Evolve an error without breaking its contract
Proposed changePractical client riskRecommended CIE exercise
Localise title or detailA client parsing the phrase may take a different branch.Keep the same type and replay two languages with the same expected machine outcome.
Change the type URIA new problem identity may replace the old one.Test existing consumers and document migration, tolerance and fallback.
Add an extensionAn overly strict client may reject a previously readable response.Add an unknown member to the consumer test and check the intended tolerance.
Remove or rename a business extensionA client action may depend on the documented field.Check the type-specific contract, observed use and compatibility plan.
Change the HTTP statusA proxy, cache or SDK may handle the response differently.Compare raw response and body through generation and intermediaries.
Add technical detailInternal paths, secrets or account information may leak.Test the public message, occurrence reference and access-controlled logs separately.

Keep a raw response example for each refusal, its type definition, the consumer test outcome and contract version. Two matching numbers do not demonstrate that the server chose the correct refusal or that another attempt has no side effects.

Provenance and snapshot limits

IANA · 6 types · registry 2026-06-26 · reviewed 2026-10-23 · CC0 1.0

IANA XML SHA-256: 2b6a7ae5a63a5f6afccd8884658393d5268d16b63d624e883fd5fe5dcf5aa57b

RFC 9457 TXT SHA-256: f2b3db92fb0bf3489cb3841a0da0c0d88dff40797b64d40b6123085183886c7b

GraphQL:错误、列表和部分数据

此语言版本的详细参考说明以英语提供。

GraphQL contract: errors do not always erase data

Define what a client may retain after resolver failure: the contract includes data shape, null scope and error paths.

  • Compare absent data, partial data and data: null.
  • Keep the original path even when a parent becomes null.
  • Test permissions, quotas and interface states separately.

Explore GraphQL responses and nullability →

GraphQL Specification · September 2025 · Published edition · September 2025

API弃用与停用

此语言版本的详细参考说明以英语提供。

Plan retirement beyond the version number

A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.

  • Distinguish Deprecation, Sunset and policy links.
  • Check that Sunset does not precede Deprecation when both dates are provided.
  • Measure remaining consumers and validate the replacement before cutover.

Compare deprecation and retirement announcements →

IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23

IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23

官方参考文献

参考文献支持该方法。 请根据您的实际情况调整检查;它们并非认证。 原始参考文献标题和源文档可能使用其他语言。

参考资料查阅日期 .