eBay 的 API 策略

在使用未能正确版本化的 SOAP API 多年之后，eBay 决定转向新的RESTful API，其中包含语义版本控制和弃用标准。他们的重点放在了可扩展性和适应性上，目标是使开发人员更容易创建使用 eBay API 的新应用程序。在一篇博客文章中，Tanya Vlahovic描述了这些概念以及它们在 API 中是如何实现的。

在 eBay 的首席公共 API 架构师 Vlahovic 看来，API 代表业务，但她强调，单独的 API 是不够的；它们必须一起使用才能给企业带来真正的价值。她将 eBays 的 API 集与烹饪进行了比较——API 是佐料，然后由开发人员社区以一些新的、创新的方式组合不同的 API 来提供一顿大餐。

要创建一个灵活和适应性强的 API 生态系统，重要的是要了解单个 API 是成功还是失败；它们是被开发人员使用还是被忽略？Vlahovic 认为，API 所有者应该非常开放，当试图改进 API 并使其得到使用时，应该从不同的角度寻找解决方案。她举了两个新 API 的例子，她认为它们改变了人们的思维方式，它们就是去年夏天发布的图像搜索和机器文本翻译。

Vlahovic 将 API 描述为做三件简单的事情：执行操作和收集数据，格式化数据，最后提供数据服务。她认为，创建 API 最简单的方法是设计直观、简单的契约，而不需要花费大量时间编写文档，然后让开发人员试用并评估它的价值。她指出，API 是面向人类开发人员的接口，而不是面向机器人的。

在新的 RESTful API 中，它们遵循三个质量级别的语义版本控制：Alpha、Beta 和正式可用。除了这些级别之外，它们还支持实验性 API。这允许早期采用者探索、测试 API，并快速反馈。

他们的弃用标准同时关注契约和运行时行为，并使用了和版本控制中相同的质量级别。当它们废弃 API 中的某个元素时，例如资源、字段或行为，这些元素通常以原始形式维护 18 个月。对于每一个新弃用的元素，都会新发布一个 API 的次要版本，并伴有一个公开声明，其中包含针对开发人员的详细说明。如果需要，这些说明中还会包括迁移说明。如果弃用导致向后不兼容，API 所有者必须决定是否发布一个新的主版本，而不是一个次要版本。

无论何时弃用一个元素，都会将 deprecated 属性添加到元素中，并更新 description 属性以反映该弃用。这两个属性在OpenAPI规范中都有定义。在运行时，它们会使用包含 299 代码的标准 Warning HTTP 响应头来发送弃用通知。这个头应该被消费者应用程序记录和监视，以便开发人员可以得到关于新更改的警告。

Vlahovic 将 API 视为使开发人员能够创建新应用程序的构建块。为了简化这项工作，eBay 提供了 SDK，抽象了一些概念。一个例子是行业标准OAuth 2.0协议，eBay 使用该协议处理授权和数据隐私问题。它们要求所有 API 客户端在使用其市场功能之前都要经过授权，因此，SDK 中包含了对这一点的支持。除了现有的开源 Java OAuth 客户端库之外，他们最近还发布了一个 C#和一个 Python 版本的库。

在早些时候的一篇博文中，Vlahovic 写了 eBay 两年的历程，他们向市场交付了一系列新的API，以及他们在那段时间中学到了什么。

原文链接：

API Strategies at eBay