在使用未能正确版本化的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，以及他们在那段时间中学到了什么。
原文链接：