Breaking Changes Bad!  API Versioning Good!

Comme toute personne qui a construit ou utilise régulièrement une API s'en rend compte tôt ou tard, les changements de rupture sont très mauvais et peuvent constituer une tache très grave sur une API par ailleurs utile. Un changement de rupture est une modification du comportement d'une API qui peut rompre l'intégration d'un utilisateur et entraîner beaucoup de frustration et une perte de confiance entre le fournisseur et l'utilisateur de l'API. Les changements de rupture exigent que les utilisateurs en soient informés à l'avance (avec les mea culpas qui les accompagnent), contrairement à un changement qui ne fait qu'apparaître, comme une nouvelle fonctionnalité intéressante. La façon d'éviter cette frustration est de mettre en place une version de l'API avec l'assurance du propriétaire de l'API qu'aucun changement surprenant ne sera introduit dans une seule et même version.

Alors, à quel point est-il difficile de versionner une API ? La vérité est que ce n'est pas difficile, mais ce qui l'est, c'est de garder un peu de bon sens en évitant de se perdre inutilement dans un nombre vertigineux de versions et de subversions appliquées à des dizaines de points de terminaison d'API aux compatibilités floues.

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 différentes opinions on how to version REST API, I hope that the story of our humble yet powerful v1 might guide you on your way to API versioning enlightenment.

REST est la meilleure solution

L'API SparkPost date de l'époque où nous étions Message Systems, avant nos aventures dans le cloud. À l'époque, nous étions occupés à faire les derniers préparatifs pour le lancement de la version bêta de Momentum 4. Il s'agissait d'une mise à niveau majeure de la version 3.x, notre MTA sur site leader sur le marché. Momentum La version 4 comprenait une toute nouvelle interface utilisateur, des analyses en temps réel et, surtout, une nouvelle API web pour l'injection et la génération de messages, la gestion des modèles et l'obtention de données sur les courriels. Notre vision était celle d'une architecture API first - où même l'interface utilisateur interagirait avec les points d'extrémité de l'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. Le first was to put the versioning directly in the URI and the second was to use an Accept header. Le first option is more explicit and less complicated, which is easier for developers.  Since we love developers, it was the logical choice.

Gouvernance des 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.

Le groupe de gouvernance a identifié un certain nombre de façons d'introduire des changements dans l'API qui sont bénéfiques pour l'utilisateur et ne constituent pas un changement radical. Il s'agit notamment de :

• Une nouvelle ressource ou un nouveau point de terminaison API

• Un nouveau paramètre facultatif

• Modification d'un point de terminaison non public de l'API

• Une nouvelle clé optionnelle dans le corps JSON POST

• Une nouvelle clé retournée dans le corps de la réponse JSON.

À l'inverse, un changement de rupture comprend tout ce qui pourrait briser l'intégration d'un utilisateur, par exemple :

• Un nouveau paramètre obligatoire

• Une nouvelle clé obligatoire dans les corps POST

• Suppression d'un point d'accès existant

• Suppression d'un point d'accès existant request method

• Un comportement interne matériellement différent d'un appel d'API - tel qu'un changement du comportement par défaut.

The Big 1.0

Au fur et à mesure que nous avons documenté et discuté de ces conventions, nous sommes également arrivés à la conclusion qu'il était dans l'intérêt de tous (y compris le nôtre !) d'éviter d'apporter des modifications radicales à l'API, car la gestion de plusieurs versions ajoute beaucoup de frais généraux. Nous avons décidé que nous devions corriger certaines choses dans notre API avant de nous engager dans la "v1".

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.

Une documentation précise

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 Schéma directeur de l'API and gérer nos documents dans 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 Rucher, 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 Jekyll to generate static docs instead.  Our latest Documentation sur l'API SparkPost now load quickly and work well on mobile devices which is important for developers who are not always sitting at their computer.

Séparer le déploiement de la diffusion

Nous avons appris très tôt l'astuce précieuse consistant à séparer un déploiement d'une version. De cette façon, il est possible de déployer fréquemment des changements lorsqu'ils sont prêts grâce à la livraison et au déploiement continus, mais nous ne les annonçons pas toujours publiquement ou ne les documentons pas en même temps. Il n'est pas rare que nous déployions un nouveau point de terminaison d'API ou une amélioration d'un point de terminaison d'API existant et que nous l'utilisions dans l'interface utilisateur ou avec des outils internes avant de le documenter publiquement et de le prendre en charge. De cette façon, nous pouvons y apporter quelques modifications pour en améliorer la convivialité ou la conformité aux normes sans craindre d'effectuer un changement radical redouté. Une fois que nous sommes satisfaits de la modification, nous l'ajoutons à notre documentation publique.

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.

De temps en temps, nous sommes tentés d'introduire des modifications de rupture à la suite de la correction de bogues. Cependant, nous avons décidé de ne pas toucher à ces particularités plutôt que de risquer de casser les intégrations des clients par souci de cohérence.

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 à la 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.