Jadi seberapa sulitkah untuk mengelola versi API? Kebenarannya adalah itu bukan hal yang sulit, tetapi yang sulit adalah mempertahankan kewarasan dengan tidak terpecah menjadi sejumlah versi dan subversi yang membingungkan yang diterapkan di puluhan titik akhir API dengan kompatibilitas yang tidak jelas.
Perubahan Buruk! Versi API Baik!
Seperti yang disadari oleh siapa pun yang telah membangun atau sering menggunakan API cepat atau lambat, perubahan yang merusak sangat buruk dan dapat menjadi cela serius pada API yang sebaliknya berguna. Perubahan yang merusak adalah perubahan pada perilaku API yang dapat merusak integrasi pengguna dan mengakibatkan banyak frustrasi serta hilangnya kepercayaan antara penyedia dan pengguna API. Perubahan yang merusak mengharuskan pengguna diberi pemberitahuan sebelumnya (dengan mea culpas yang disertakan) daripada perubahan yang hanya muncul, seperti fitur baru yang menyenangkan. Cara untuk menghindari frustrasi tersebut adalah dengan memversioning API dengan jaminan dari pemilik API bahwa tidak akan ada perubahan mengejutkan yang diperkenalkan dalam versi tunggal apa pun.
Jadi, seberapa sulit untuk memversioning API? Kenyataannya tidaklah sulit, tetapi yang sulit adalah menjaga kewarasan dengan tidak secara tidak perlu berkembang menjadi sejumlah besar versi dan subversi yang memusingkan yang diterapkan di puluhan titik akhir API dengan kompatibilitas yang tidak jelas.
Kami memperkenalkan v1 dari API tiga tahun lalu dan tidak menyadari bahwa itu akan tetap kuat hingga hari ini. Jadi bagaimana kami terus menyediakan API pengiriman email terbaik selama lebih dari dua tahun tetapi tetap mempertahankan versi API yang sama? Stabilitas ini sangat penting bagi pengembang yang membangun aplikasi dengan email APIs dalam infrastruktur cloud, di mana keandalan dan konsistensi sangat penting. Meskipun ada banyak pendapat berbeda tentang bagaimana memversioning REST APIs, saya berharap cerita tentang v1 kami yang sederhana namun kuat dapat membimbing Anda menuju pencerahan versi API.
REST Is Best
API Governance
Dengan konvensi penomoran versi yang dipilih, kami memiliki lebih banyak pertanyaan. Kapan kita akan menaikkan versi? Apa itu perubahan yang merusak? Apakah kita akan merevisi seluruh API atau hanya endpoint tertentu? Di SparkPost, kami memiliki berbagai tim yang bekerja pada bagian-bagian berbeda dari API kami. Di dalam tim-tim tersebut, orang-orang bekerja pada endpoint yang berbeda pada waktu yang berbeda. Oleh karena itu, sangat penting bagi API kami untuk konsisten dalam penggunaan konvensi. Ini lebih besar dari sekadar penomoran versi.
Kami membentuk kelompok tata kelola termasuk insinyur yang mewakili setiap tim, anggota dari tim Manajemen Produk, dan CTO kami. Kelompok ini bertanggung jawab untuk menetapkan, mendokumentasikan, dan menegakkan konvensi API kami di seluruh tim. Saluran Slack tata kelola API juga sangat membantu untuk perdebatan yang hidup mengenai topik ini.
Kelompok tata kelola mengidentifikasi sejumlah cara yang dapat diperkenalkan perubahan pada API yang bermanfaat bagi pengguna dan tidak merupakan perubahan yang merusak. Ini termasuk:
Sumber daya atau endpoint API baru
Parameter opsional baru
Perubahan pada endpoint API non-publik
Kunci opsional baru dalam tubuh POST JSON
Kunci baru yang dikembalikan dalam tubuh respons JSON
Sebaliknya, perubahan yang merusak mencakup apa pun yang dapat merusak integrasi pengguna seperti:
Parameter wajib baru
Kunci wajib baru dalam tubuh POST
Pencabutan endpoint yang ada
Pencabutan metode permintaan endpoint yang ada
Perilaku internal yang berbeda secara material dari panggilan API – seperti perubahan pada perilaku default.
The Big 1.0
Seperti yang kami dokumentasikan dan diskusikan konvensi-konvensi ini, kami juga sampai pada kesimpulan bahwa ini adalah kepentingan terbaik setiap orang (termasuk kami!) untuk menghindari perubahan yang mengganggu pada API karena mengelola beberapa versi menambah cukup banyak beban. Kami memutuskan bahwa ada beberapa hal yang harus kami perbaiki dengan API sebelum berkomitmen ke "v1".
Mengirim email sederhana memerlukan terlalu banyak usaha. Untuk "menjaga hal-hal sederhana tetap sederhana" kami memperbarui badan POST untuk memastikan bahwa kedua kasus penggunaan sederhana dan kompleks dapat diakomodasi. Format baru ini juga lebih tahan terhadap masa depan. Kedua kami menangani masalah dengan endpoint Metrics. Endpoint ini menggunakan parameter "group_by" yang akan mengubah format badan respons GET sehingga kunci pertama akan menjadi nilai dari parameter group by. Itu tampaknya tidak terlalu RESTful, jadi kami memisahkan setiap grup menjadi endpoint terpisah. Akhirnya kami mengaudit setiap endpoint dan membuat perubahan kecil di sana-sini untuk memastikan mereka sesuai dengan standar.
Dokumentasi Akurat
Penting untuk memiliki dokumentasi API yang akurat dan dapat digunakan untuk menghindari perubahan yang merusak, baik yang disengaja maupun tidak. Kami memutuskan untuk menggunakan pendekatan dokumentasi API sederhana dengan memanfaatkan bahasa Markdown yang disebut API Blueprint dan manage our docs in Github. Komunitas kami berkontribusi dan meningkatkan dokumen open source ini. Kami juga memelihara serangkaian dokumen yang tidak dipublikasi di Github untuk API internal dan endpoints.
Awalnya, kami menerbitkan dokumen kami ke Apiary, alat yang bagus untuk membuat prototipe dan menerbitkan dokumen API. Namun, memasukkan Apiary ke dalam situs web kami tidak berfungsi di perangkat seluler, jadi sekarang kami menggunakan Jekyll untuk menghasilkan dokumen statis sebagai gantinya. SparkPost API docs terbaru kami sekarang dimuat dengan cepat dan bekerja dengan baik di perangkat seluler, yang penting bagi pengembang yang tidak selalu duduk di depan komputer mereka.
Memisahkan Deployment dari Release
Kami belajar sejak awal trik berharga untuk memisahkan penerapan dari rilis. Dengan cara ini, kami dapat sering menerapkan perubahan ketika sudah siap melalui pengiriman dan penerapan terus menerus, tetapi kami tidak selalu mengumumkan atau mendokumentasikan mereka secara publik pada saat yang sama. Tidak jarang bagi kami untuk menerapkan endpoint API baru atau peningkatan pada endpoint API yang ada dan menggunakannya dari dalam UI atau dengan alat internal sebelum kami mendokumentasikannya dan mendukungnya secara publik. Dengan begitu, kami dapat melakukan beberapa penyesuaian untuk kegunaan atau kesesuaian dengan standar tanpa khawatir membuat perubahan yang merusak. Setelah kami puas dengan perubahannya, kami menambahkannya ke dokumentasi publik kami.
Aduh!
Adalah adil untuk mengakui bahwa ada kalanya kami tidak memenuhi idealisme "tiada perubahan besar" kami dan ini layak dipelajari. Pada suatu kesempatan, kami memutuskan akan lebih baik bagi pengguna jika properti tertentu secara default diatur ke benar daripada salah. Setelah kami menerapkan perubahan tersebut, kami menerima beberapa keluhan dari pengguna karena perilaku telah berubah secara tak terduga. Kami membalik perubahan tersebut dan menambahkan pengaturan pada tingkat akun – pendekatan yang tentu saja lebih ramah pengguna.
Sesekali kami tergoda untuk memperkenalkan perubahan besar sebagai hasil dari perbaikan bug. Namun, kami memutuskan untuk membiarkan keanehan ini daripada berisiko merusak integrasi pelanggan demi konsistensi.
Ada kasus langka di mana kami membuat keputusan serius untuk membuat perubahan yang signifikan – seperti menghentikan sumber daya atau metode API – demi kepentingan komunitas pengguna yang lebih besar dan hanya setelah memastikan bahwa ada sedikit atau tidak ada dampak pada pengguna. Sebagai contoh, kami dengan sengaja membuat pilihan untuk mengubah perilaku respons dari Suppression API tetapi hanya setelah mempertimbangkan manfaat dan dampaknya bagi komunitas dan dengan hati-hati mengkomunikasikan perubahan tersebut kepada pengguna kami. Namun, kami tidak akan pernah memperkenalkan perubahan yang memiliki kemungkinan kecil berdampak langsung pada pengiriman email produksi pengguna.
