REST API版本控制和sdk

时间:2014-07-08 12:46:22

标签: rest sdk versioning

githubtwilioalgoliastormpath等服务如何与不同语言的SDK一起保留休息api?他们是使用像enunciate这样的工具生成这样的代码还是他们自己维护客户端代码?我猜对于github,它们是开源的客户端库。我的问题是:

  1. 如何在rest api更改和相应的SDK更改之间进行同步。

  2. 其他版本的最佳做法是什么,以及他们的sdk?有哪些必须注意的常见陷阱?

1 个答案:

答案 0 :(得分:3)

在Algolia,我们在REST API之上开发了十几个API客户端。老实说,我必须说我们为了创造所有这些而遭受了很多痛苦/ o \我希望以下要点有助于:

为什么我们创建自己的API客户端而不是仅使用库/工具来生成它们(这对REST API客户端来说很常见)?

  • 能够达到99.99%的SLA,我们决定在我们的API客户端实施“重试策略” - > Algolia索引总是在3台机器上复制 - >如果一个人关闭,API客户端将重试其他的 - >这不能由通用库处理
  • 为了达到最佳性能,我们希望确保控制HTTP保持活动的方式 - >大多数通用库也不能处理它
  • 我们希望尽快强制使用HTTPS

我们是如何进行的?

  • 一开始,我们并不是所有这些语言的超级流利;所以我们开始研究用每种语言实现的其他API客户端来理解最佳实践
  • 我们得到了来自1个人的Node.js和1个来自python
  • 的帮助
  • 但直到我们决定将所有这些内容移至Travis.CI +插件代码覆盖率以达到80-95%的代码覆盖率+自动化测试时才真的不行 - >显然,我们发现了很多错误:)
  • 我们发布新功能后,我们需要更新所有API客户端 - >非常痛苦...
  • 为了简化README生成,我们开发了一个小工具,为所有语言生成README。这是超级Algolia特定的,但你可以看看https://github.com/algolia/algoliasearch-client-readme-generator - >同样非常痛苦的引导:)

我们学到的东西:

    无论语言如何,
  • 保持所有这些都是完全相同的 - >来自客户POV的超级明白
  • 如果您的社区正在构建API客户端,那很酷;但他们在测试中可能不会那么深 - >我们正在测试所有API客户端中的所有功能 - >质量
  • 如果我们需要
  • ,我们会再次这样做