评估API定义时应检查哪些内容？
API定义：它是什么
API定义是描述客户端应如何调用API以及API将如何响应的书面契约。它通常包括端点路径、请求/响应格式（例如JSON字段）、数据类型、必填与可选参数、身份验证与权限、速率限制、错误格式，以及任何声明的时间或顺序要求。
在自动化交易场景中，API定义至关重要，因为每一个下游步骤——数据摄取、信号逻辑、执行决策和报告——都依赖于API所保证的内容与它仅“尝试”提供的内容之间的区别。评估的关键目标是理解哪些部分是稳定的机制，哪些部分会随市场状况、系统负载和提供商策略而变化。
如何检查API定义（客观清单）
- 契约完整性（检查项）
- 明确列出所有端点和方法。
- 定义了请求和响应的模式，包括字段含义和数据类型。
- 存在正常响应和每种已记录错误类型的示例。
- 声明了身份验证和授权要求（例如，凭证如何提供以及允许的访问权限）。
- 行为细节（“工作原理”部分）
- 确认API是否定义了跨调用的顺序或一致性（例如，“最新”是否与时间戳绑定）。
- 检查时间戳的表示方式（格式、时区，以及反映的是事件时间还是处理时间）。
- 验证分页、过滤和限制的工作方式，包括最大页面大小和默认值。
- 可变条件与稳定机制
- 将稳定元素（模式、参数规则、已记录的错误代码）与可变元素（延迟、数据缺失、市场波动、因负载导致的限流）分开。
- 将任何关于“实时”或“流式传输”的声明视为需通过测试或示例响应验证的行为主张，而非固定承诺。
- 证据与文档证明 寻找可用来验证契约的实现工件：
- 包含示例负载和错误响应的文档。
- 版本管理策略，说明变更如何引入以及旧版本支持的时长。
- 测试资源，如沙箱环境、模拟端点或已记录的示例调用。
- 明确的限制声明（红旗） 识别文档中沉默或模糊的空白点：
- 关键字段缺少定义。
- 错误语义不明确（例如，错误是否可重试）。
- 未描述背压、速率限制行为或部分中断期间会发生什么。
证据或示例： “验证”意味着什么
基于证据评估的一个实际例子是运行脚本化调用，涵盖以下内容：
- 一次“正常路径”请求，并确认响应字段是否符合文档中定义的模式。
- 至少一个边界条件，例如应触发已记录错误的无效参数。
- 通过测量往返时间并将其与任何声明的时间预期进行比较，进行延迟/时间检查。
假设示例（明确陈述）：如果你从自己的系统时钟测量响应时间，你假设你的时钟是合理同步的。如果没有该假设，时间比较可能会产生误导。
需要考虑的限制和故障模式
至少评估一种重大故障模式：
- 数据缺口：API可能返回不完整的历史记录、缺失事件或延迟更新。
- 延迟和排序问题：即使存在时间戳，调用顺序也可能不匹配事件顺序。
- 速率限制或限流：过多请求可能导致延迟或结构化错误。
- 模式漂移：API版本可能更改字段、类型或必需参数。
- 身份验证/权限失败：令牌可能过期，或访问范围可能因环境而异。
历史关系不能确立未来结果。即使示例响应看起来一致，当提供商更新服务或系统负载和市场波动变化时，未来行为仍可能改变。结果还因成本、执行方式和司法管辖区而异，因此应将API定义视为契约描述，而非性能保证。
验证标准和后续问题
在集成前使用明确的“完成标准”（klaarcriterium）：
- 你可以将每个必需参数和每个返回字段映射到文档中的明确定义。
- 你可以在测试环境中重现文档中描述的成功和错误响应。
- 你已记录关于时间、重试和数据完整性的假设。
- 你已制定应对速率限制、未知字段和版本变更的计划。
评估期间应提出的后续问题：
- API对时间戳和排序的文档化一致性模型具体是什么？
- 哪些错误是可重试的？提供了哪些退避建议？