Breaking Changes Bad!  API Versioning Good!

Seperti yang disadari oleh siapa pun yang telah membuat atau secara teratur menggunakan API, cepat atau lambat, perubahan yang merusak sangat buruk dan dapat menjadi cacat yang sangat serius pada API yang seharusnya berguna. Perubahan yang merusak adalah perubahan pada perilaku API yang dapat merusak integrasi pengguna dan mengakibatkan banyak frustrasi dan hilangnya kepercayaan antara penyedia API dan pengguna. Perubahan yang merusak mengharuskan pengguna untuk diberitahukan terlebih dahulu (dengan mea culpa yang menyertainya) daripada perubahan yang muncul begitu saja, seperti fitur baru yang menyenangkan. Cara untuk menghindari frustrasi tersebut adalah dengan membuat versi API dengan jaminan dari pemilik API bahwa tidak akan ada perubahan yang mengejutkan yang diperkenalkan dalam satu versi.

Jadi, seberapa sulitkah membuat versi API? Sebenarnya tidak, tetapi yang sulit adalah mempertahankan kewarasan dengan tidak perlu terpaku pada jumlah versi dan subversi yang memusingkan yang diterapkan pada lusinan titik akhir API dengan kompatibilitas yang tidak jelas.

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 pendapat yang berbeda 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.

Istirahat adalah yang terbaik

API SparkPost berasal dari saat kami masih menjadi Message Systems, sebelum petualangan kami di cloud. Pada saat itu kami sibuk membuat persiapan akhir untuk peluncuran beta Momentum 4. Ini merupakan peningkatan besar ke versi 3.x, MTA on-premise kami yang terdepan di pasar. Momentum 4 mencakup UI yang sama sekali baru, analitik waktu nyata, dan yang paling penting adalah API web baru untuk injeksi dan pembuatan pesan, mengelola templat, dan mendapatkan metrik email. Visi kami adalah arsitektur API pertama - di mana bahkan UI akan berinteraksi dengan titik akhir 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. The first was to put the versioning directly in the URI and the second was to use an Accept header. The first option is more explicit and less complicated, which is easier for developers.  Since we love developers, it was the logical choice.

Tata Kelola 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.

Kelompok tata kelola mengidentifikasi sejumlah cara perubahan yang dapat dilakukan pada API yang bermanfaat bagi pengguna dan bukan merupakan perubahan yang melanggar. Hal-hal tersebut antara lain:

• Sumber daya baru atau titik akhir API

• Parameter opsional baru

• Perubahan ke titik akhir API non-publik

• Kunci opsional baru dalam badan JSON POST

• Kunci baru yang dikembalikan dalam badan respons JSON

Sebaliknya, perubahan yang merusak termasuk apa pun yang dapat merusak integrasi pengguna seperti:

• Parameter baru yang diperlukan

• Kunci baru yang diperlukan dalam badan POST

• Penghapusan titik akhir yang sudah ada

• Penghapusan titik akhir yang sudah ada request method

• Perilaku internal yang berbeda secara material dari panggilan API - seperti perubahan pada perilaku default.

The Big 1.0

Ketika kami mendokumentasikan dan mendiskusikan konvensi-konvensi ini, kami juga sampai pada kesimpulan bahwa semua orang (termasuk kami!) sebaiknya menghindari membuat perubahan yang merusak pada API karena mengelola beberapa versi akan menambah sedikit biaya tambahan. Kami memutuskan bahwa ada beberapa hal yang harus kami perbaiki dengan API kami sebelum beralih ke "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.

Dokumentasi yang Akurat

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 Cetak Biru API and mengelola dokumen kami di 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 Tempat pemeliharaan lebah, 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 Dokumen API SparkPost now load quickly and work well on mobile devices which is important for developers who are not always sitting at their computer.

Memisahkan Penerapan dari Rilis

Kami belajar sejak awal tentang trik yang sangat berharga untuk memisahkan penerapan dari rilis. Dengan cara ini, kami dapat sering menerapkan perubahan ketika sudah siap melalui pengiriman dan penerapan berkelanjutan, tetapi kami tidak selalu mengumumkan atau mendokumentasikannya secara bersamaan. Tidak jarang kami menerapkan endpoint API baru atau peningkatan pada endpoint API yang sudah ada dan menggunakannya dari dalam UI atau dengan alat bantu internal sebelum kami mendokumentasikannya secara publik dan mendukungnya. Dengan begitu, kita dapat melakukan beberapa penyesuaian untuk kegunaan atau kesesuaian dengan standar tanpa khawatir membuat perubahan yang ditakuti. Setelah kami puas dengan perubahannya, kami menambahkannya ke dokumentasi publik kami.

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.

Terkadang kami tergoda untuk memperkenalkan perubahan yang melanggar sebagai hasil dari perbaikan bug. Namun, kami memutuskan untuk membiarkan keistimewaan ini daripada mengambil risiko merusak integrasi pelanggan demi konsistensi.

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 ke 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.