经验分享:eBay的API智慧设计


单个API不足以让开发人员具有创新性。当API一起使用时,API非常强大,因此组合维度才是最重要的.
API允许组织大规模地为其合作伙伴提供对数据和功能的访问。可扩展和适应性强的API生态系统使开发人员更容易进行创新。建立这样一个生态系统是一个前进的过程,面临许多技术挑战。
API代表业务,使其能够扩展到新的上下文和体验。整个API组合为组织带来了价值。单个API不足以让开发人员具有创新性。API一起使用时功能强大,因此组合维度才是最重要的。组合使用让我们的API可以访问有价值的eBay市场功能。使用烹饪类比API集成,我们相信我们提供健康的成分。我们的开发人员社区应该发挥创造力,并提出很好的方案来满足客户的需求。 

开发生态系统
“正是知识发展最令人满意的结果之一就是不断开放新的和更大的前景。” - 尼古拉·特斯拉
最简单的API方法是设计直观,直接的合同。API是人们的接口。它们适用于人类开发人员。(人工智能仍然很重要。)目标是与API集成,而不需要花太多时间在文档上或提交开发人员技术支持票。API就像一个讲笑话,如果需要进一步解释通常表示其已经具有不必要的复杂性。
通常,API做三件简单的事情。(我将跳过有时落后于以下步骤的所有技术挑战。)

  • 执行操作并收集数据
  • 格式化数据
  • 提供数据

评估API的价值需要时间; 了解发布API是成功还是失败。必须接受变革并强调灵活且适应性强的API生态系统。如果你拥有的只是一把锤子,那么每个问题看起来都像钉子一样。 当满足开发人员的需求具有挑战性时,API所有者应该改变观点并寻找不同的解决方案来改进API组合。通常,有许多方法可以解决问题。构建开发人员生态系统很困难,有很多技术(和其他)挑战,但如果做得好,它会朝着正确的方向扩展。
在商业世界中,破坏性力量如今是强大的。增强和虚拟现实和人工智能,语音和图像识别,以及各种自学系统,无处不在。这些创新有能力极大地重塑购买和销售体验,并改变人们与数字世界互动的方式。在eBay,我们通过API公开这些功能。去年夏天发布的图像机器文本翻译仅仅是一个开始。
另一方面,有时API功能会因各种原因而消失:业务策略或策略更改,不符合业务目标,难以集成。因此,还需要标准化API生命周期的这一方面。

API弃用版本的标准
在eBay上,我们有API版本控制和弃用的规范。版本控制在开发人员中是一个有争议的话题。这是API世界中最常见的争论之一。在处理不正确版本的基于SOAP的API 10年之后,我们决定使用新的现代RESTful API来改变方法。我们遵循语义版本控制并定义了alpha,beta和一般可用性质量级别。此外,我们支持实验API。这些功能的目的是探索,测试并获得API早期采用者和合作伙伴的反馈。
我们的API弃用标准主要关注API契约和运行时行为。弃用规范适用于所有API质量级别:alpha,beta和一般可用性以及实验功能。弃用API版本或整个API是API生命周期的最后阶段。当API不符合业务目标时,它是最佳选择。API弃用的一些原因是:

  • 业务政策或战略变革
  • 实验能力/ API不再符合业务目标
  • 无效
  • 使用率低

可以弃用的API元素包括:
  • 资源/方法
  • 领域
  • 枚举值
  • 查询参数
  • HTTP标头
  • 行为
  • API(主要)版本
  • 所有主要版本的整个API

不推荐使用的API元素以原始形式保留18个月。此政策的例外情况是可能的,并适用于关键业务决策。透明的公告随附任何API元素的弃用。它包含开发人员的详细说明,包括迁移计划(如果适用)。API弃用公告发布在我们的Developer Portal上,可能包含其他通信渠道。
在某些情况下,不推荐使用的元素会导致向后不兼容的更改。由API产品所有者决定方法:继续弃用或发布新的主要版本。
我们使用OpenAPI规范中的deprecated属性来声明不推荐使用的API元素:方法,字段,查询参数和标头。此外,我们更改OpenAPI规范描述属性以反映弃用。以下示例适用于弃用的actualDeliveryDate字段。 

ShippingFulfillment:

 type: "object"

 properties:

   actualDeliveryDate:

     type:
"string"

     description:
"This field has been deprecated. For instructions on how to migrate to the new version, visit eBay Developer Portal. The date the purchase order was delivered."

     deprecated: true

对于任何新弃用的API元素,我们会发布一个新的次要API版本。此类版本需要API文档更新,它包括新的API合同以及与开发人员的正确通信。

HTTP响应标头以传达弃用
在运行时,我们利用标准的警告 HTTP响应头和  299代码来反映不推荐使用的API元素。开发人员将记录和监视Warning标头的用途。根据HTTP协议规范,299代码(杂项持久警告)不是用于弃用的专用代码。为了简化客户端上此信息的使用,我们仅对已弃用的API元素使用299代码。在任何API弃用的情况下,无论HTTP状态代码如何,警告 HTTP标头都存在于每个适用的响应中。
当一个方法,查询参数或HTTP标头不推荐使用时,这些响应中带有警告Warning标头,作为响应一部分。
对于字段、枚举值或行为不推荐使用时,来自使用这些元素或相关元素的所有方法的响应都指定了  警告Warning标头。
API​​主要版本不推荐使用时,每个方法的响应都包含一个  Warning标头。如果整个API弃用,这适用于所有API主要版本。
API客户端应记录HTTP弃用标头并具有适当的警报和监控。eBay开发者门户网站上记录了说明和示例,作为与eBay RESTful公共API集成最佳实践的一部分  。

句法
Warning: <warn-code> <warn-agent> <warn-text> [<warn-date>]

<warn-code>
一个三位数的警告号码。始终为299(杂项持久警告)以反映已弃用的API元素。这里的299代码不是HTTP响应状态代码; 它只是警告标题内容的一部分。

<warn-agent>
warn-agent值是API主机名。示例:api.ebay.com,api.sandbox.ebay.com

<warn-text>
警告头包含的警告文本,其中包含有关弃用的简要信息。警告文本有一个指向公共API文档的链接,用于解释弃用。警告文本旨在呈现给人类用户或记录。

<warn-date>
包括弃用日期。格式与RFC 7231日期/时间格式定义的HTTP Date标头相同。

候选字段
可以生成多个警告,具有相同的299代码和不同的警告文本作为响应。这是为了反映在不同时间点弃用的多个API元素。

例子
在Account API中不推荐使用返回策略字段restockingFee和extendedHolidayReturnsOffered。下面警告 HTTP标头是存在于用于RETURN_POLICY资源定义的所有方法。

Warning: 299 api.ebay.com "Deprecated return policy fields: restockingFee and extendedHolidayReturnsOffered. We will keep supporting them for the next 18 months. For more information, visit https://developer.ebay.com/api-docs/sell/account/deprecation.html" “Wed, 15 Jun 2018 00:00:00 GMT”

不推荐使用Account API的第1版时,低于Account API版本1下的所有方法HTTP标头出现警告。

Warning: 299 api.ebay.com "You are using a deprecated version of the API. We will keep supporting it for the next 18 months. For instructions on how to migrate to the new version, visit https://developer.ebay.com/api-docs/sell/account/deprecation.html" “Wed, 15 Jun 2018 00:00:00 GMT”

我们考虑使用标准的Sunset HTTP标头向客户传达API弃用的事实,但由于以下原因而放弃了这个想法:

  • 在Sunset 响应头仍处于草案
  • 在Sunset 响应头指示资源或API即将退休。它不适合弃用其他API元素:字段,枚举值和行为。
  • 不支持多个Sunset标头来传达在不同时间发生的多个弃用。当资源预期无响应时,Sunset响应标头包含单个时间戳。 

我们还在跟踪今年努力引入(和标准化)  Deprecation HTTP响应标头,以向客户发出API弃用信号。

软件开发工具包
“我们就是要反复做。那么,卓越不是一种行为,而是一种习惯。“ - 亚里士多德
API是使应用程序能够交互的中介。它们是开发人员创新和创造产品的基石。另一方面,SDK是通过抽象一些概念(例如各种横切关注点)来简化构建块的工作的工具。SDK使开发人员能够创建新的应用程序或新的构建块。
今年,我们继续使用API​​的开源工具。我们最近发布了C#Python OAuth客户端库,可以简化与API的集成。这是以前开源的Java OAuth客户端库的补充。为了获得适当的授权并解决数据隐私问题,我们利用行业标准的OAuth 2.0协议。所有eBay API都要求客户获得使用我们的市场功能的授权。利用我们的库时,只需几行代码即可与eBay OAuth服务集成。
Feed API向我们的合作伙伴公开了最多的库存选择。这包括新的日常用品以及稀有商品  - 如果世界上存在某种东西,最有可能在eBay上出售。合作伙伴使用我们的数据Feed创建丰富的项目选择,并使用户能够找到完美的版本。Feed SDK抽象下载和大文件操作,简化了典型的复杂库存管理。它们允许全球的授权合作伙伴以编程方式访问大量的eBay项目,并根据他们的商业模式策划他们选择的库存。在去年的Java Feed SDK之后,我们最近发布了Python客户端
去年夏天的eBay Connect上,我们宣布OpenAPI文档可用于我们的RESTful API。我们证明了与只读功能的集成需要几分钟时间。我们的库可以进一步简化。我们开源的SDK不是提供黑盒子,而是为开发人员提供完全透明的集成功能。(我们欢迎开发者社区的贡献!)