Breaking Changes Bad!  API Versioning Good!

正如任何建立过或经常使用API的人迟早会意识到的那样，破坏性变化是非常糟糕的，它可能是一个原本有用的API上的非常严重的污点。破坏性变化是对API行为的改变，它可能会破坏用户的整合，并导致大量的挫折和API提供者与用户之间的信任损失。破坏性变化需要提前通知用户（伴随着道歉），而不是像一个令人愉快的新功能那样，突然出现的变化。避免这种挫折感的方法是在API所有者保证在任何一个版本中都不会有令人惊讶的变化的情况下，对API进行改版。

那么，对一个API进行版本管理有多难呢？事实上，这并不难，难的是保持一定的理智，不至于无谓地演变成令人眼花缭乱的版本和颠覆，在几十个API端点上应用，而且兼容性不明确。

We introduced v1 of the API three years ago and did not realize that it would be going strong to this day. So how have we continued to provide the best email delivery API for over two years but still maintain the same API version? While there are many 不同意见 on how to version REST 应用程序接口, I hope that the story of our humble yet powerful v1 might guide you on your way to API versioning enlightenment.

REST是最好的

SparkPost应用程序接口起源于我们还是消息系统公司的时候，那时我们还没有开始云计算。当时，我们正忙着为Momentum 4 测试版的推出做最后的准备。这是我们市场领先的内部 MTA 3.x 版本的重大升级。Momentum 4 包括全新的用户界面、实时分析，以及最重要的用于邮件注入和生成、管理模板和获取邮件指标的全新 Web API。我们的愿景是采用 API 优先架构--甚至用户界面也将与 API 端点互动。

One of the earliest and best decisions we made was to adopt a RESTful style. Since the late 2000s representational state transfer (REST) based web APIs are the de-facto standard of cloud APIs. Using HTTP and JSON makes it easy for developers, regardless of which programming language they use – PHP, Ruby, and Java – to integrate with our API without knowing or caring about our underlying technology.

Choosing to use the RESTful architecture was easy. Choosing a versioning convention was not so easy. Initially we punted on the question of versioning by not versioning the beta at all. However, within a couple months the beta was in the hands of a few customers and we began building out our cloud service.  Time to version. We evaluated two versioning conventions. ǞǞǞ first was to put the versioning directly in the URI and the second was to use an Accept header. ǞǞǞ first option is more explicit and less complicated, which is easier for developers.  Since we love developers, it was the logical choice.

API治理

With a versioning convention selected we had more questions. When would we bump the version? What is a breaking change?  Would we reversion the whole API or just certain endpoints? At SparkPost, we have multiple teams working on different parts of our API. Within those teams, people work on different endpoints at different times. Therefore, it’s very important that our API is consistent in the use of conventions. This was bigger than versioning.

We established a governance group including engineers representing each team, a member of the Product Management team, and our CTO. This group is responsible for establishing, documenting, and enforcing our API conventions across all teams. An API governance Slack channel also comes in handy for lively debates on the topic.

治理小组确定了一些可以引入API的变化，这些变化对用户有利，并且不构成破坏性变化。这些方法包括

• 一个新的资源或API端点

• 一个新的可选参数

• 对一个非公开的API端点的改变

• 在JSON POST正文中的一个新的可选键

• 在JSON响应体中返回一个新的密钥

相反，破坏性变化包括任何可能破坏用户整合的东西，例如。

• 一个新的必要参数

• POST机构中的一个新的必要键

• 删除一个现有的端点

• 删除一个现有的端点 request method

• 一个API调用的内部行为有实质性的不同--比如对默认行为的改变。

大1.0

当我们记录和讨论这些约定时，我们也得出了这样的结论：避免对API进行破坏性的修改符合每个人（包括我们！）的最佳利益，因为管理多个版本会增加相当多的开销。我们决定，在提交 "v1 "版本之前，我们应该修复我们的API的一些问题。

Sending a simple email required way too much effort.  To “keep the simple things simple” we updated the POST body to ensure that both simple and complex use cases are accommodated.  The new format was more future-proof as well.  Secondly we addressed a problem with the Metrics endpoint. This endpoint used a “group_by” parameter that would change the format of the GET response body such that the first key would be the value of the group by parameter. That did not seem very RESTful so we broke each group by into a separate endpoint. Finally we audited each endpoint and made minor changes here and there to ensure they conformed with the standards.

准确的文件

It is important to have accurate and usable API documentation to avoid breaking changes, of the deliberate or unintentional kind. We decided to use a simple API documentation approach leveraging a Markdown language called API蓝图 and 在Github中管理我们的文档. Our community contributes and improves upon these open source docs.  We also maintain a nonpublic set of docs in Github for internal APIs and endpoints.

Initially, we published our docs to 养蜂场, a great tool for prototyping and publishing API docs. However, embedding Apiary into our website doesn’t work on mobile devices so we now use 杰基尔 to generate static docs instead.  Our latest SparkPost API文档 now load quickly and work well on mobile devices which is important for developers who are not always sitting at their computer.

将部署与发布分开

我们很早就学会了把部署和发布分开的宝贵技巧。这样就可以通过持续交付和部署，在变化准备好的时候经常部署，但我们并不总是在同一时间公开宣布或记录这些变化。我们部署一个新的API端点或对现有API端点的增强，并在公开记录和支持它之前从用户界面或内部工具中使用它，这种情况并不罕见。这样我们就可以对它的可用性或标准的一致性做一些调整，而不必担心做出可怕的破坏性改变。一旦我们对这个变化感到满意，我们就把它添加到我们的公共文档中。

Doh!

It is only fair to admit that there have been times where we have not lived up to our “no breaking changes” ideals and these are worth learning from. On one occasion we decided it would be better for users if a certain property defaulted to true instead of false. After we deployed the change we received several complaints from users since the behavior had changed unexpectedly.  We reverted the change and added an account level setting – a much more user friendly approach for sure.

偶尔我们也会因为错误的修复而引入一些破坏性的变化。然而，我们决定不去管这些特异功能，而不是为了一致性而冒着破坏客户集成的风险。

There are rare cases where we made the serious decision to make a breaking change – such as deprecating an API resource or method – in the interest of the greater user community and only after confirming that there is little to no impact to users. For example, we deliberately made the choice to alter the response behavior of the Suppression API but only after carefully weighing the benefits and impacts 到 community and carefully communicating the change to our users. However, we would never introduce a change that has a remote possibility of directly impacting the sending of a user’s production email.