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 menggunakan API secara teratur cepat atau lambat, perubahan mendasar sangat buruk dan bisa menjadi cacat serius pada API yang seharusnya berguna. Perubahan mendasar adalah perubahan pada perilaku API yang dapat merusak integrasi pengguna dan mengakibatkan banyak frustrasi dan hilangnya kepercayaan antara penyedia API dan pengguna. Perubahan mendasar mengharuskan pengguna diberi tahu sebelumnya (dengan penjelasan lengkap) daripada perubahan yang tiba-tiba muncul, 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 mengejutkan yang diperkenalkan dalam satu versi pun.
Jadi, seberapa sulitkah membuat versi API? Kenyataannya tidak sulit, tetapi yang sulit adalah menjaga kewarasan dengan tidak perlu menyusut menjadi sejumlah besar versi dan subversi yang diterapkan di puluhan titik akhir API dengan kompatibilitas yang tidak jelas.
Kami memperkenalkan v1 dari API tiga tahun yang lalu dan tidak menyadari bahwa itu akan tetap kuat hingga hari ini. Jadi, bagaimana kami terus memberikan API pengiriman email terbaik selama lebih dari dua tahun tetapi masih mempertahankan versi API yang sama? Meskipun ada banyak pendapat berbeda tentang cara membuat versi REST API, saya berharap bahwa kisah v1 yang rendah hati namun kuat kami dapat membimbing Anda dalam perjalanan menuju pencerahan versi API.
REST Is Best
API Governance
Dengan konvensi versi yang dipilih, kami memiliki lebih banyak pertanyaan. Kapan kita akan menaikkan versinya? Apa itu perubahan yang memecahkan? Apakah kita akan mereversi seluruh API atau hanya titik akhir tertentu? Di SparkPost, kami memiliki beberapa tim yang bekerja di bagian yang berbeda dari API kami. Di dalam tim-tim tersebut, orang bekerja pada titik akhir yang berbeda pada waktu yang berbeda pula. Oleh karena itu, sangat penting bahwa API kami konsisten dalam penggunaan konvensi. Ini lebih besar dari sekadar versi.
Kami membentuk kelompok tata kelola yang mencakup insinyur yang mewakili setiap tim, anggota dari tim Manajemen Produk, dan CTO kami. Kelompok ini bertanggung jawab untuk membuat, mendokumentasikan, dan menegakkan konvensi API kami di semua tim. Saluran Slack tata kelola API juga berguna untuk debat yang hidup tentang topik ini.
Kelompok tata kelola mengidentifikasi sejumlah cara perubahan dapat diperkenalkan ke API yang bermanfaat bagi pengguna dan tidak termasuk perubahan yang memecahkan. Ini termasuk:
Sumber daya baru atau titik akhir API
Parameter opsional baru
Perubahan ke titik akhir API yang tidak publik
Kunci opsional baru dalam tubuh JSON POST
Kunci baru yang dikembalikan dalam tubuh respons JSON
Sebaliknya, perubahan yang memecahkan termasuk apa pun yang dapat mengganggu integrasi pengguna seperti:
Parameter wajib baru
Kunci wajib baru dalam tubuh POST
Pencabutan titik akhir yang ada
Pencabutan metode permintaan titik akhir yang ada
Perilaku internal yang secara materi berbeda dari panggilan API – seperti perubahan pada perilaku default.
The Big 1.0
Seperti yang telah kami dokumentasikan dan diskusikan, kami juga sampai pada kesimpulan bahwa demi kepentingan terbaik semua orang (termasuk kami!), sebaiknya menghindari membuat perubahan yang menghancurkan pada API karena mengelola banyak versi menambah beban kerja yang cukup banyak. Kami memutuskan bahwa ada beberapa hal yang perlu kami perbaiki dengan API kami sebelum berkomitmen ke "v1".
Mengirim email sederhana memerlukan terlalu banyak usaha. Untuk "menjaga agar hal-hal sederhana tetap sederhana" kami memperbarui badan POST untuk memastikan bahwa baik penggunaan kasus sederhana maupun kompleks dapat terakomodasi. Format baru tersebut juga lebih tahan masa depan. Selain itu, kami menyelesaikan masalah dengan endpoint Metrics. Endpoint ini menggunakan parameter "group_by" yang akan mengubah format badan respons GET sedemikian rupa sehingga kunci pertama adalah nilai dari parameter group by. Itu tampak tidak terlalu RESTful jadi kami memecah setiap group by menjadi endpoint terpisah. Akhirnya kami memeriksa setiap endpoint dan membuat sedikit perubahan di sana-sini untuk memastikan mereka sesuai dengan standar.
Dokumentasi Akurat
Adalah penting untuk memiliki dokumentasi API yang akurat dan dapat digunakan untuk menghindari perubahan yang merusak, baik yang disengaja maupun tidak sengaja. Kami memutuskan untuk menggunakan pendekatan dokumentasi API sederhana dengan memanfaatkan bahasa Markdown yang disebut API Blueprint dan mengelola dokumen kami di Github. Komunitas kami berkontribusi dan meningkatkan dokumen sumber terbuka ini. Kami juga menjaga sekumpulan dokumen nonpublik di Github untuk API dan titik akhir internal.
Pada awalnya, kami menerbitkan dokumen kami ke Apiary, alat yang hebat untuk membuat prototipe dan menerbitkan dokumen API. Namun, memasukkan Apiary ke dalam situs web kami tidak berfungsi pada perangkat seluler jadi sekarang kami menggunakan Jekyll untuk menghasilkan dokumen statis sebagai gantinya. Dokumen SparkPost API terbaru kami sekarang memuat dengan cepat dan berfungsi baik pada 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.
