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.
Business in a box.
Temukan solusi kami.
Bicaralah kepada tim penjualan kami
Perubahan Buruk! Versi API Baik!
Seperti yang disadari oleh siapa pun yang telah membangun atau secara rutin menggunakan API, perubahan yang merusak sangat buruk dan dapat menjadi noda serius pada API yang berguna. Perubahan yang merusak adalah perubahan pada perilaku API yang dapat merusak integrasi pengguna dan mengakibatkan banyak kekecewaan serta hilangnya kepercayaan antara penyedia dan pengguna API. Perubahan yang merusak harus pengguna diberitahu sebelumnya (dengan mea culpas yang menyertai) daripada perubahan yang tiba-tiba muncul, seperti fitur baru yang menyenangkan. Cara untuk menghindari kekecewaan itu adalah dengan melakukan versi API dengan jaminan dari pemilik API bahwa tidak akan ada perubahan mengejutkan yang diperkenalkan dalam satu versi apa pun.
Jadi seberapa sulit melakukan versi API? Kenyataannya tidak, tetapi yang sulit adalah menjaga kewarasan dengan tidak tanpa perlu berkembang menjadi sejumlah besar versi dan subversi yang membingungkan yang diterapkan di berbagai titik akhir API dengan kompatibilitas yang tidak jelas.
Kami memperkenalkan v1 API tiga tahun 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 namun tetap mempertahankan versi API yang sama? Sementara ada banyak pendapat berbeda tentang cara versi REST API, saya berharap cerita kami yang sederhana namun kuat v1 dapat membimbing Anda menuju pencerahan versi API.
REST Is Best
API Governance
Dengan ketetapan versi yang dipilih, kami memiliki lebih banyak pertanyaan. Kapan kami akan menambah versi? Apa itu perubahan besar? Apakah kami akan memperbarui versi seluruh API atau hanya endpoint tertentu? Di SparkPost, kami memiliki beberapa tim yang bekerja pada bagian yang berbeda dari API kami. Dalam tim-tim tersebut, orang bekerja pada endpoint yang berbeda pada waktu yang berbeda pula. Oleh karena itu, sangat penting bahwa API kami konsisten dalam penggunaan ketetapan. Ini lebih besar dari sekedar versi.
Kami membentuk kelompok pengelolaan yang terdiri dari insinyur yang mewakili setiap tim, seorang anggota dari tim Manajemen Produk, dan CTO kami. Kelompok ini bertanggung jawab untuk menetapkan, mendokumentasikan, dan menegakkan ketetapan API kami di semua tim. Kanal Slack pengelolaan API juga berguna untuk perdebatan sengit mengenai topik ini.
Kelompok pengelolaan mengidentifikasi sejumlah cara perubahan dapat diperkenalkan ke API yang menguntungkan pengguna dan tidak merupakan perubahan besar. Termasuk di dalamnya:
Sumber daya atau endpoint API baru
Parameter opsional baru
Perubahan ke endpoint API yang tidak publik
Kunci opsional baru dalam badan JSON POST
Kunci baru yang dikembalikan dalam badan respons JSON
Sebaliknya, perubahan besar termasuk apa pun yang dapat merusak integrasi pengguna seperti:
Parameter baru yang diperlukan
Kunci baru yang diperlukan dalam badan POST
Pencabutan endpoint yang ada
Pencabutan metode permintaan endpoint yang ada
Perilaku internal yang secara materi berbeda dari sebuah panggilan API – seperti perubahan pada perilaku default.
The Big 1.0
Saat kami mendokumentasikan dan membahas konvensi ini, kami juga sampai pada kesimpulan bahwa adalah kepentingan terbaik semua orang (termasuk kami!) untuk menghindari membuat perubahan signifikan pada API karena mengelola beberapa versi menambah beban kerja yang cukup banyak. Kami memutuskan bahwa ada beberapa hal yang harus kami perbaiki dengan API kami sebelum berkomitmen ke “v1”.
Mengirim email sederhana membutuhkan terlalu banyak usaha. Untuk “menjaga hal-hal sederhana tetap sederhana” kami memperbarui badan POST untuk memastikan bahwa baik kasus penggunaan sederhana maupun kompleks dapat dipenuhi. Format baru ini juga lebih tahan terhadap masa depan. Kedua, kami mengatasi masalah dengan endpoint Metrics. Endpoint ini menggunakan parameter “group_by” yang akan mengubah format badan tanggapan GET sehingga kunci pertama adalah nilai dari parameter group by. Hal itu tidak terlihat sangat RESTful, jadi kami memisahkan setiap group by menjadi endpoint terpisah. Akhirnya, kami meninjau 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 disengaja. 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 memperbaiki dokumen sumber terbuka ini. Kami juga memelihara satu set dokumen tidak publik di Github untuk API dan titik akhir internal.
Awalnya, kami menerbitkan dokumen kami ke Apiary, alat hebat untuk prototipe dan menerbitkan dokumen API. Namun, menanamkan Apiary ke dalam situs web kami tidak berfungsi di perangkat seluler jadi sekarang kami menggunakan Jekyll untuk menghasilkan dokumen statis. Dokumen SparkPost API terbaru kami sekarang memuat dengan cepat dan berfungsi 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 wajar untuk mengakui bahwa ada saat-saat di mana kami tidak memenuhi ideal "tidak ada perubahan yang merugikan" dan ini patut dipelajari. Pada satu kesempatan, kami memutuskan bahwa akan lebih baik bagi pengguna jika properti tertentu secara default diatur ke true daripada false. Setelah kami menerapkan perubahan tersebut, kami menerima beberapa keluhan dari pengguna karena perilaku telah berubah secara tak terduga. Kami membatalkan perubahan tersebut dan menambahkan pengaturan tingkat akun – pendekatan yang jauh lebih ramah pengguna tentunya.
Sesekali kami tergoda untuk memperkenalkan perubahan yang merugikan sebagai hasil dari perbaikan bug. Namun, kami memutuskan untuk membiarkan keanehan ini tetap ada daripada mengambil risiko merusak integrasi pelanggan demi konsistensi.
Ada kasus langka di mana kami membuat keputusan serius untuk membuat perubahan yang merugikan – seperti menghentikan sumber daya API atau metode – demi kepentingan komunitas pengguna yang lebih besar dan hanya setelah memastikan bahwa tidak ada dampak yang signifikan bagi pengguna. Misalnya, kami dengan sengaja membuat pilihan untuk mengubah perilaku respons dari Suppression API tetapi hanya setelah mempertimbangkan dengan hati-hati manfaat dan dampaknya terhadap komunitas serta berkomunikasi dengan hati-hati kepada pengguna kami. Namun, kami tidak akan pernah mengenalkan perubahan yang memiliki kemungkinan sedikit pun untuk secara langsung mempengaruhi pengiriman email produksi pengguna.
