设想一个订购网站将新订单发送到业务运营系统。运营系统已经保存订单，但网站始终没有收到确认。网站是否应该重试？这样会不会创建第二个订单？这个假设场景说明了 API 契约为什么对业务运营很重要。契约描述双方预期的行为，也包括一次成功演示可能永远不会揭示的情况。
本页内容
从业务流程和数据责任开始
梳理从用户操作到结果确认的一次完整交互。以订单为例，需要明确谁生成订单编号、哪个系统决定是否接受订单，以及客户在哪里查看状态。收到请求与接受订单可能是不同的事件，必须区分。同时，确定各项信息可以由哪个系统修改。如果双方都能编辑配送地址，契约就需要规定更新处理规则，而不能假设最新界面中的值就是权威数据。
- 明确订单、客户和状态信息的负责方。
- 说明用户必须立即看到什么结果。
- 识别接收系统之后必须发送哪些更新。
具体定义字段
为每条消息记录必填信息、允许值，以及信息缺失时的含义。价格需要注明币种并明确其解释方式；时间戳需要约定时区规则。可以用一个贴近实际的示例订单讨论这些规则：例如，“已取消”指整个订单还是某个商品？空地址表示未知，还是被有意删除？还应说明每个调用方可以读取或修改哪些记录。这些决策同时影响接口规格和应用使用体验，仅仅统一字段名称并不能解决它们。
规定重复请求的行为和有用的错误反馈
针对示例订单，可以提出这样的规则：在约定的保留期限内，以相同请求标识符再次发送相同订单详情时，返回已有订单编号；若使用同一标识符发送不同详情，则产生由调用方处理的冲突。应明确标识符的适用范围和保留期限。随后，将需要纠正的错误与暂时性故障区分开来。仅凭超时无法确定订单是否已保存，因此调用方需要有办法先核实结果，再决定下一步操作。
- 缺少配送地址：返回字段级说明，修改请求后再重新发送。
- 结果不确定：查询请求标识符，并核对其记录状态。
- 服务暂时故障：遵循约定的重试策略，避免每次尝试都创建新的订单标识。
约定契约的测试与变更方式
请两个团队共同演练成功下单、重复请求、无效地址和确认中断等情况，检查双方对每种情况是否预期相同的结果。将这些例子与规格说明放在一起，在集成发生变化时继续使用。明确谁负责批准变更、通知对接团队和调查事件。交接内容应解释支持人员如何在不暴露多余客户信息的情况下追踪请求，以及如何向现有接口使用方引入不兼容的变更。