Praktik Terbaik Versi API RESTful: Mengapa v1 adalah yang terbaik
Chris McFadden
24 Mei 2017
1 min read
Poin Penting
Versi API mencegah perubahan yang merusak dan mempertahankan kepercayaan antara penyedia API dan pengembang.
Konvensi versi yang jelas membantu menghindari campuran versi yang kacau di seluruh endpoint.
API RESTful yang dipasangkan dengan URI versi yang sederhana dan eksplisit menjaga integrasi tetap intuitif bagi pengembang.
Kelompok pengelolaan memastikan konsistensi di seluruh tim, mencegah perubahan yang merusak yang tidak disengaja.
Tidak semua perubahan memerlukan versi baru — hanya yang merusak integrasi yang ada.
Dokumentasi yang baik sangat penting untuk menghindari kebingungan dan mencegah perubahan yang merusak yang tidak disengaja.
Memisahkan penyebaran dari perilisan memungkinkan tim untuk menguji dan memperbaiki endpoint dengan aman sebelum mengumumkannya.
Ketika perubahan yang merusak tidak terhindarkan, mereka harus dievaluasi dan dikomunikasikan dengan hati-hati.
Sorotan Tanya jawab
Mengapa versi API itu penting?
Ini mencegah perubahan mendadak yang tidak diinginkan untuk pengembang yang mengintegrasikan dengan API Anda, melindungi kepercayaan, dan memastikan stabilitas jangka panjang untuk aplikasi yang bergantung pada perilaku yang konsisten.
Apa itu perubahan yang merusak dalam API?
Setiap modifikasi yang mengubah bagaimana integrasi yang ada berfungsi — seperti menghapus endpoint, mengubah default, menambahkan kolom yang diperlukan, atau memodifikasi format respons.
Mengapa SparkPost memilih REST sebagai fondasi untuk API mereka?
Penggunaan HTTP dan JSON oleh REST memudahkan pengembang di berbagai bahasa (PHP, Ruby, Java, dll.) untuk berintegrasi tanpa memerlukan pengetahuan khusus tentang sistem yang mendasarinya.
Bagaimana SparkPost menentukan metode versi yang digunakannya?
Mereka mengevaluasi versi header Accept vs. versi URI dan memilih versi URI karena itu eksplisit, sederhana, dan lebih ramah bagi pengembang.
Apa peran kelompok tata kelola API?
Ini menetapkan standar, menegakkan konsistensi, dan mencegah tim memperkenalkan perubahan yang bertentangan dengan konvensi atau merusak kompatibilitas.
Jenis perubahan apa yang tidak dianggap sebagai perubahan yang merusak?
Menambahkan parameter opsional baru, memperkenalkan endpoint baru, menambahkan kunci baru dalam payload JSON, atau mengubah endpoint yang tidak publik — apa pun yang tidak mengganggu perilaku yang ada.
Perubahan apa yang dianggap merusak?
Menambahkan parameter yang diperlukan, menghapus endpoint, mengubah perilaku default, mengubah struktur respons, atau memperkenalkan field JSON yang diperlukan.
Mengapa dokumentasi yang akurat itu penting?
Ini mencegah perubahan yang tidak disengaja, membantu pengembang memahami perilaku, dan memastikan tim memperbarui API dengan andal. SparkPost menggunakan Markdown (API Blueprint) dan GitHub untuk menjaga kejelasan dan keterbukaan.
Apa manfaat memisahkan penyebaran dari rilis?
Tim dapat secara terus-menerus menerapkan endpoint baru atau peningkatan secara internal, mengujinya dalam alur kerja yang nyata, memperbaiki perilaku, dan hanya merilis secara publik setelah stabil — menghindari paparan prematur yang berpotensi merusak.
Apa yang terjadi jika perubahan besar menjadi diperlukan?
Ini harus jarang, dibenarkan oleh manfaat yang jelas, dievaluasi dengan cermat untuk dampak pengguna, dan dikomunikasikan secara menyeluruh. Contoh: mengubah API Penekanan hanya setelah mengonfirmasi efek minimal dan memberikan pemberitahuan.
Jadi seberapa sulit sih untuk memversioning sebuah API? Kenyataannya, itu tidak sulit, tetapi yang sulit adalah mempertahankan sedikit akal sehat dengan tidak terjebak dalam sejumlah versi dan subversi yang membingungkan yang diterapkan di berbagai endpoint API dengan kompatibilitas yang tidak jelas.
Jadi seberapa sulit sih untuk memversioning sebuah API? Kenyataannya, itu tidak sulit, tetapi yang sulit adalah mempertahankan sedikit akal sehat dengan tidak terjebak dalam sejumlah versi dan subversi yang membingungkan yang diterapkan di berbagai endpoint API dengan kompatibilitas yang tidak jelas.
Jadi seberapa sulit sih untuk memversioning sebuah API? Kenyataannya, itu tidak sulit, tetapi yang sulit adalah mempertahankan sedikit akal sehat dengan tidak terjebak dalam sejumlah versi dan subversi yang membingungkan yang diterapkan di berbagai endpoint API dengan kompatibilitas yang tidak jelas.
Duh!
Adalah wajar untuk mengakui bahwa ada kalanya kami tidak memenuhi idealisme “tanpa perubahan yang merusak” kami dan hal-hal ini layak untuk dipelajari. Pada satu kesempatan, kami memutuskan bahwa akan lebih baik bagi pengguna jika properti tertentu secara default diatur ke benar alih-alih salah. Setelah kami menerapkan perubahan tersebut, kami menerima beberapa keluhan dari pengguna karena perilakunya telah berubah secara tidak terduga. Kami membatalkan perubahan tersebut dan menambahkan pengaturan tingkat akun - pendekatan yang jauh lebih ramah pengguna, tentu saja.
Sekali-sekali kami tergoda untuk memperkenalkan perubahan yang merusak sebagai akibat 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 melakukan perubahan yang merusak - seperti mendepresiasi sumber daya atau metode API - demi kepentingan komunitas pengguna yang lebih besar dan hanya setelah mengonfirmasi bahwa tidak ada atau sedikit dampak pada pengguna. Sebagai contoh, kami dengan sengaja membuat pilihan untuk mengubah perilaku respons dari API Penekanan tetapi hanya setelah mempertimbangkan dengan cermat manfaat dan dampaknya bagi komunitas dan berkomunikasi dengan hati-hati tentang perubahan tersebut kepada pengguna kami. Namun, kami tidak pernah akan memperkenalkan perubahan yang memiliki kemungkinan kecil untuk berdampak langsung pada pengiriman email produksi pengguna.
Adalah wajar untuk mengakui bahwa ada kalanya kami tidak memenuhi idealisme “tanpa perubahan yang merusak” kami dan hal-hal ini layak untuk dipelajari. Pada satu kesempatan, kami memutuskan bahwa akan lebih baik bagi pengguna jika properti tertentu secara default diatur ke benar alih-alih salah. Setelah kami menerapkan perubahan tersebut, kami menerima beberapa keluhan dari pengguna karena perilakunya telah berubah secara tidak terduga. Kami membatalkan perubahan tersebut dan menambahkan pengaturan tingkat akun - pendekatan yang jauh lebih ramah pengguna, tentu saja.
Sekali-sekali kami tergoda untuk memperkenalkan perubahan yang merusak sebagai akibat 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 melakukan perubahan yang merusak - seperti mendepresiasi sumber daya atau metode API - demi kepentingan komunitas pengguna yang lebih besar dan hanya setelah mengonfirmasi bahwa tidak ada atau sedikit dampak pada pengguna. Sebagai contoh, kami dengan sengaja membuat pilihan untuk mengubah perilaku respons dari API Penekanan tetapi hanya setelah mempertimbangkan dengan cermat manfaat dan dampaknya bagi komunitas dan berkomunikasi dengan hati-hati tentang perubahan tersebut kepada pengguna kami. Namun, kami tidak pernah akan memperkenalkan perubahan yang memiliki kemungkinan kecil untuk berdampak langsung pada pengiriman email produksi pengguna.
Adalah wajar untuk mengakui bahwa ada kalanya kami tidak memenuhi idealisme “tanpa perubahan yang merusak” kami dan hal-hal ini layak untuk dipelajari. Pada satu kesempatan, kami memutuskan bahwa akan lebih baik bagi pengguna jika properti tertentu secara default diatur ke benar alih-alih salah. Setelah kami menerapkan perubahan tersebut, kami menerima beberapa keluhan dari pengguna karena perilakunya telah berubah secara tidak terduga. Kami membatalkan perubahan tersebut dan menambahkan pengaturan tingkat akun - pendekatan yang jauh lebih ramah pengguna, tentu saja.
Sekali-sekali kami tergoda untuk memperkenalkan perubahan yang merusak sebagai akibat 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 melakukan perubahan yang merusak - seperti mendepresiasi sumber daya atau metode API - demi kepentingan komunitas pengguna yang lebih besar dan hanya setelah mengonfirmasi bahwa tidak ada atau sedikit dampak pada pengguna. Sebagai contoh, kami dengan sengaja membuat pilihan untuk mengubah perilaku respons dari API Penekanan tetapi hanya setelah mempertimbangkan dengan cermat manfaat dan dampaknya bagi komunitas dan berkomunikasi dengan hati-hati tentang perubahan tersebut kepada pengguna kami. Namun, kami tidak pernah akan memperkenalkan perubahan yang memiliki kemungkinan kecil untuk berdampak langsung pada pengiriman email produksi pengguna.
Perubahan Besar Buruk! Versi API Baik!
Seperti yang disadari oleh siapa pun yang telah membangun atau rutin menggunakan API, perubahan yang merusak itu sangat buruk dan bisa menjadi cacat yang sangat serius pada API yang sebaliknya berguna. Perubahan yang merusak adalah perubahan pada perilaku API yang dapat merusak integrasi pengguna dan menyebabkan banyak frustrasi serta kehilangan kepercayaan antara penyedia API dan pengguna. Perubahan yang merusak mengharuskan pengguna diberi tahu sebelumnya (dengan permintaan maaf yang menyertainya) daripada perubahan yang tiba-tiba muncul, seperti fitur baru yang menyenangkan. Cara untuk menghindari frustrasi tersebut adalah dengan memberikan versi API dengan jaminan dari pemilik API bahwa tidak akan ada perubahan mengejutkan yang diperkenalkan dalam satu versi tunggal.
Jadi, betapa sulitnya untuk memberikan versi pada API? Kenyataannya, itu tidak sulit, tetapi yang sulit adalah menjaga agar tetap waras dengan tidak jatuh ke dalam ribuan 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 terus berjalan 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 API email di infrastruktur cloud, di mana keandalan dan konsistensi sangat penting. Meskipun ada banyak pendapat berbeda tentang cara memberikan versi pada API REST, saya berharap bahwa kisah v1 kami yang sederhana namun kuat dapat membimbing Anda dalam perjalanan menuju pencerahan pengversian API.
Seperti yang disadari oleh siapa pun yang telah membangun atau rutin menggunakan API, perubahan yang merusak itu sangat buruk dan bisa menjadi cacat yang sangat serius pada API yang sebaliknya berguna. Perubahan yang merusak adalah perubahan pada perilaku API yang dapat merusak integrasi pengguna dan menyebabkan banyak frustrasi serta kehilangan kepercayaan antara penyedia API dan pengguna. Perubahan yang merusak mengharuskan pengguna diberi tahu sebelumnya (dengan permintaan maaf yang menyertainya) daripada perubahan yang tiba-tiba muncul, seperti fitur baru yang menyenangkan. Cara untuk menghindari frustrasi tersebut adalah dengan memberikan versi API dengan jaminan dari pemilik API bahwa tidak akan ada perubahan mengejutkan yang diperkenalkan dalam satu versi tunggal.
Jadi, betapa sulitnya untuk memberikan versi pada API? Kenyataannya, itu tidak sulit, tetapi yang sulit adalah menjaga agar tetap waras dengan tidak jatuh ke dalam ribuan 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 terus berjalan 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 API email di infrastruktur cloud, di mana keandalan dan konsistensi sangat penting. Meskipun ada banyak pendapat berbeda tentang cara memberikan versi pada API REST, saya berharap bahwa kisah v1 kami yang sederhana namun kuat dapat membimbing Anda dalam perjalanan menuju pencerahan pengversian API.
Seperti yang disadari oleh siapa pun yang telah membangun atau rutin menggunakan API, perubahan yang merusak itu sangat buruk dan bisa menjadi cacat yang sangat serius pada API yang sebaliknya berguna. Perubahan yang merusak adalah perubahan pada perilaku API yang dapat merusak integrasi pengguna dan menyebabkan banyak frustrasi serta kehilangan kepercayaan antara penyedia API dan pengguna. Perubahan yang merusak mengharuskan pengguna diberi tahu sebelumnya (dengan permintaan maaf yang menyertainya) daripada perubahan yang tiba-tiba muncul, seperti fitur baru yang menyenangkan. Cara untuk menghindari frustrasi tersebut adalah dengan memberikan versi API dengan jaminan dari pemilik API bahwa tidak akan ada perubahan mengejutkan yang diperkenalkan dalam satu versi tunggal.
Jadi, betapa sulitnya untuk memberikan versi pada API? Kenyataannya, itu tidak sulit, tetapi yang sulit adalah menjaga agar tetap waras dengan tidak jatuh ke dalam ribuan 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 terus berjalan 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 API email di infrastruktur cloud, di mana keandalan dan konsistensi sangat penting. Meskipun ada banyak pendapat berbeda tentang cara memberikan versi pada API REST, saya berharap bahwa kisah v1 kami yang sederhana namun kuat dapat membimbing Anda dalam perjalanan menuju pencerahan pengversian API.
REST Adalah yang Terbaik
API SparkPost berasal dari masa kami menjadi Sistem Pesan, sebelum petualangan kami di awan. Pada saat itu, kami sibuk membuat persiapan akhir untuk peluncuran beta Momentum 4. Ini adalah peningkatan besar dari versi 3.x, MTA unggulan kami di tempat. Momentum 4 mencakup UI baru yang sepenuhnya, analitik waktu nyata, dan yang paling penting, API web baru untuk injeksi dan generasi pesan, mengelola template, dan mendapatkan metrik email. Visi kami adalah arsitektur API pertama – di mana bahkan UI akan berinteraksi dengan titik akhir API.
Salah satu keputusan awal dan terbaik yang kami buat adalah mengadopsi gaya RESTful. Sejak akhir 2000-an, transfer status representasional (REST) berbasis API web adalah standar de-facto API cloud. Menggunakan HTTP dan JSON memudahkan pengembang, terlepas dari bahasa pemrograman yang mereka gunakan – PHP, Ruby, dan Java – untuk terintegrasi dengan API kami tanpa mengetahui atau memperhatikan teknologi dasar kami. Namun, membangun API cloud-native pada skala dapat menghadirkan tantangan infrastruktur yang tidak terduga, seperti batas skala DNS yang kami temui di AWS saat menangani lalu lintas API denganVolume tinggi.
Memilih untuk menggunakan arsitektur RESTful sangat mudah. Memilih konvensi versi tidak semudah itu. Pada awalnya, kami menghindari pertanyaan versi dengan tidak memversioning beta sama sekali. Namun, dalam beberapa bulan, beta telah ada di tangan beberapa pelanggan dan kami mulai membangun layanan cloud kami. Waktu untuk versi. Kami mengevaluasi dua konvensi versi.
Pendekatan versi | Bagaimana cara kerjanya | Trade-off |
|---|---|---|
Versi URI | Versi termasuk dalam jalur titik akhir | Eksplisit dan mudah dipahami |
Versi header Accept | Versi disampaikan melalui header HTTP | Kurang terlihat, lebih rumit bagi pengembang |
Yang pertama adalah menempatkan versi langsung di URI dan yang kedua adalah menggunakan header Accept. Opsi pertama lebih eksplisit dan kurang rumit, yang lebih mudah bagi pengembang. Karena kami mencintai pengembang, itu adalah pilihan yang logis.
API SparkPost berasal dari masa kami menjadi Sistem Pesan, sebelum petualangan kami di awan. Pada saat itu, kami sibuk membuat persiapan akhir untuk peluncuran beta Momentum 4. Ini adalah peningkatan besar dari versi 3.x, MTA unggulan kami di tempat. Momentum 4 mencakup UI baru yang sepenuhnya, analitik waktu nyata, dan yang paling penting, API web baru untuk injeksi dan generasi pesan, mengelola template, dan mendapatkan metrik email. Visi kami adalah arsitektur API pertama – di mana bahkan UI akan berinteraksi dengan titik akhir API.
Salah satu keputusan awal dan terbaik yang kami buat adalah mengadopsi gaya RESTful. Sejak akhir 2000-an, transfer status representasional (REST) berbasis API web adalah standar de-facto API cloud. Menggunakan HTTP dan JSON memudahkan pengembang, terlepas dari bahasa pemrograman yang mereka gunakan – PHP, Ruby, dan Java – untuk terintegrasi dengan API kami tanpa mengetahui atau memperhatikan teknologi dasar kami. Namun, membangun API cloud-native pada skala dapat menghadirkan tantangan infrastruktur yang tidak terduga, seperti batas skala DNS yang kami temui di AWS saat menangani lalu lintas API denganVolume tinggi.
Memilih untuk menggunakan arsitektur RESTful sangat mudah. Memilih konvensi versi tidak semudah itu. Pada awalnya, kami menghindari pertanyaan versi dengan tidak memversioning beta sama sekali. Namun, dalam beberapa bulan, beta telah ada di tangan beberapa pelanggan dan kami mulai membangun layanan cloud kami. Waktu untuk versi. Kami mengevaluasi dua konvensi versi.
Pendekatan versi | Bagaimana cara kerjanya | Trade-off |
|---|---|---|
Versi URI | Versi termasuk dalam jalur titik akhir | Eksplisit dan mudah dipahami |
Versi header Accept | Versi disampaikan melalui header HTTP | Kurang terlihat, lebih rumit bagi pengembang |
Yang pertama adalah menempatkan versi langsung di URI dan yang kedua adalah menggunakan header Accept. Opsi pertama lebih eksplisit dan kurang rumit, yang lebih mudah bagi pengembang. Karena kami mencintai pengembang, itu adalah pilihan yang logis.
API SparkPost berasal dari masa kami menjadi Sistem Pesan, sebelum petualangan kami di awan. Pada saat itu, kami sibuk membuat persiapan akhir untuk peluncuran beta Momentum 4. Ini adalah peningkatan besar dari versi 3.x, MTA unggulan kami di tempat. Momentum 4 mencakup UI baru yang sepenuhnya, analitik waktu nyata, dan yang paling penting, API web baru untuk injeksi dan generasi pesan, mengelola template, dan mendapatkan metrik email. Visi kami adalah arsitektur API pertama – di mana bahkan UI akan berinteraksi dengan titik akhir API.
Salah satu keputusan awal dan terbaik yang kami buat adalah mengadopsi gaya RESTful. Sejak akhir 2000-an, transfer status representasional (REST) berbasis API web adalah standar de-facto API cloud. Menggunakan HTTP dan JSON memudahkan pengembang, terlepas dari bahasa pemrograman yang mereka gunakan – PHP, Ruby, dan Java – untuk terintegrasi dengan API kami tanpa mengetahui atau memperhatikan teknologi dasar kami. Namun, membangun API cloud-native pada skala dapat menghadirkan tantangan infrastruktur yang tidak terduga, seperti batas skala DNS yang kami temui di AWS saat menangani lalu lintas API denganVolume tinggi.
Memilih untuk menggunakan arsitektur RESTful sangat mudah. Memilih konvensi versi tidak semudah itu. Pada awalnya, kami menghindari pertanyaan versi dengan tidak memversioning beta sama sekali. Namun, dalam beberapa bulan, beta telah ada di tangan beberapa pelanggan dan kami mulai membangun layanan cloud kami. Waktu untuk versi. Kami mengevaluasi dua konvensi versi.
Pendekatan versi | Bagaimana cara kerjanya | Trade-off |
|---|---|---|
Versi URI | Versi termasuk dalam jalur titik akhir | Eksplisit dan mudah dipahami |
Versi header Accept | Versi disampaikan melalui header HTTP | Kurang terlihat, lebih rumit bagi pengembang |
Yang pertama adalah menempatkan versi langsung di URI dan yang kedua adalah menggunakan header Accept. Opsi pertama lebih eksplisit dan kurang rumit, yang lebih mudah bagi pengembang. Karena kami mencintai pengembang, itu adalah pilihan yang logis.
Tata Kelola API
Dengan konvensi versi yang dipilih, kami memiliki lebih banyak pertanyaan. Kapan kami akan meningkatkan versi? Apa itu perubahan yang merusak? Apakah kami akan melakukan versi ulang pada seluruh API atau hanya pada titik akhir tertentu? Di SparkPost, kami memiliki beberapa tim yang bekerja pada berbagai bagian API kami. Di dalam tim-tim tersebut, orang-orang bekerja pada titik akhir yang berbeda pada waktu yang berbeda. Oleh karena itu, sangat penting bagi API kami untuk konsisten dalam penggunaan konvensi. Ini lebih besar daripada versi.
Kami membentuk grup tata kelola yang terdiri dari para insinyur yang mewakili setiap tim, seorang anggota tim Manajemen Produk, dan CTO kami. Grup ini bertanggung jawab untuk menetapkan, mendokumentasikan, dan menegakkan konvensi API kami di seluruh tim. Saluran Slack tata kelola API juga berguna untuk debat yang hidup tentang topik ini.
Grup tata kelola mengidentifikasi sejumlah cara perubahan dapat diperkenalkan ke API yang menguntungkan pengguna dan tidak merupakan perubahan yang merusak.
Jenis perubahan | Dianggap merusak? | Alasan |
|---|---|---|
Sumber daya atau titik akhir baru | Tidak | Tidak mempengaruhi integrasi yang ada |
Parameter opsional baru | Tidak | Panggilan yang ada tetap valid |
Kunci JSON opsional baru | Tidak | Klien dapat mengabaikannya dengan aman |
Bidang respons baru | Tidak | Kompatibel secara mundur bagi pengguna |
Parameter wajib baru | Ya | Merusak permintaan yang ada |
Kunci POST wajib baru | Ya | Membatalkan paylod yang ada |
Menghapus titik akhir | Ya | Integrasi yang ada gagal |
Mengubah perilaku default | Ya | Merubah hasil yang diharapkan |
Ini termasuk:
Sumber daya baru atau titik akhir API
Parameter opsional baru
Perubahan pada titik akhir API yang tidak publik
Kunci opsional baru dalam tubuh POST JSON
Kunci baru yang dikembalikan dalam tubuh respons JSON
Sebaliknya, perubahan yang merusak termasuk apa saja yang dapat merusak integrasi pengguna, seperti:
Parameter wajib baru
Kunci wajib baru dalam tubuh POST
Pemusnahan titik akhir yang ada
Pemusnahan metode permintaan titik akhir yang ada
Perilaku internal API yang sangat berbeda – seperti perubahan pada perilaku default.
Dengan konvensi versi yang dipilih, kami memiliki lebih banyak pertanyaan. Kapan kami akan meningkatkan versi? Apa itu perubahan yang merusak? Apakah kami akan melakukan versi ulang pada seluruh API atau hanya pada titik akhir tertentu? Di SparkPost, kami memiliki beberapa tim yang bekerja pada berbagai bagian API kami. Di dalam tim-tim tersebut, orang-orang bekerja pada titik akhir yang berbeda pada waktu yang berbeda. Oleh karena itu, sangat penting bagi API kami untuk konsisten dalam penggunaan konvensi. Ini lebih besar daripada versi.
Kami membentuk grup tata kelola yang terdiri dari para insinyur yang mewakili setiap tim, seorang anggota tim Manajemen Produk, dan CTO kami. Grup ini bertanggung jawab untuk menetapkan, mendokumentasikan, dan menegakkan konvensi API kami di seluruh tim. Saluran Slack tata kelola API juga berguna untuk debat yang hidup tentang topik ini.
Grup tata kelola mengidentifikasi sejumlah cara perubahan dapat diperkenalkan ke API yang menguntungkan pengguna dan tidak merupakan perubahan yang merusak.
Jenis perubahan | Dianggap merusak? | Alasan |
|---|---|---|
Sumber daya atau titik akhir baru | Tidak | Tidak mempengaruhi integrasi yang ada |
Parameter opsional baru | Tidak | Panggilan yang ada tetap valid |
Kunci JSON opsional baru | Tidak | Klien dapat mengabaikannya dengan aman |
Bidang respons baru | Tidak | Kompatibel secara mundur bagi pengguna |
Parameter wajib baru | Ya | Merusak permintaan yang ada |
Kunci POST wajib baru | Ya | Membatalkan paylod yang ada |
Menghapus titik akhir | Ya | Integrasi yang ada gagal |
Mengubah perilaku default | Ya | Merubah hasil yang diharapkan |
Ini termasuk:
Sumber daya baru atau titik akhir API
Parameter opsional baru
Perubahan pada titik akhir API yang tidak publik
Kunci opsional baru dalam tubuh POST JSON
Kunci baru yang dikembalikan dalam tubuh respons JSON
Sebaliknya, perubahan yang merusak termasuk apa saja yang dapat merusak integrasi pengguna, seperti:
Parameter wajib baru
Kunci wajib baru dalam tubuh POST
Pemusnahan titik akhir yang ada
Pemusnahan metode permintaan titik akhir yang ada
Perilaku internal API yang sangat berbeda – seperti perubahan pada perilaku default.
Dengan konvensi versi yang dipilih, kami memiliki lebih banyak pertanyaan. Kapan kami akan meningkatkan versi? Apa itu perubahan yang merusak? Apakah kami akan melakukan versi ulang pada seluruh API atau hanya pada titik akhir tertentu? Di SparkPost, kami memiliki beberapa tim yang bekerja pada berbagai bagian API kami. Di dalam tim-tim tersebut, orang-orang bekerja pada titik akhir yang berbeda pada waktu yang berbeda. Oleh karena itu, sangat penting bagi API kami untuk konsisten dalam penggunaan konvensi. Ini lebih besar daripada versi.
Kami membentuk grup tata kelola yang terdiri dari para insinyur yang mewakili setiap tim, seorang anggota tim Manajemen Produk, dan CTO kami. Grup ini bertanggung jawab untuk menetapkan, mendokumentasikan, dan menegakkan konvensi API kami di seluruh tim. Saluran Slack tata kelola API juga berguna untuk debat yang hidup tentang topik ini.
Grup tata kelola mengidentifikasi sejumlah cara perubahan dapat diperkenalkan ke API yang menguntungkan pengguna dan tidak merupakan perubahan yang merusak.
Jenis perubahan | Dianggap merusak? | Alasan |
|---|---|---|
Sumber daya atau titik akhir baru | Tidak | Tidak mempengaruhi integrasi yang ada |
Parameter opsional baru | Tidak | Panggilan yang ada tetap valid |
Kunci JSON opsional baru | Tidak | Klien dapat mengabaikannya dengan aman |
Bidang respons baru | Tidak | Kompatibel secara mundur bagi pengguna |
Parameter wajib baru | Ya | Merusak permintaan yang ada |
Kunci POST wajib baru | Ya | Membatalkan paylod yang ada |
Menghapus titik akhir | Ya | Integrasi yang ada gagal |
Mengubah perilaku default | Ya | Merubah hasil yang diharapkan |
Ini termasuk:
Sumber daya baru atau titik akhir API
Parameter opsional baru
Perubahan pada titik akhir API yang tidak publik
Kunci opsional baru dalam tubuh POST JSON
Kunci baru yang dikembalikan dalam tubuh respons JSON
Sebaliknya, perubahan yang merusak termasuk apa saja yang dapat merusak integrasi pengguna, seperti:
Parameter wajib baru
Kunci wajib baru dalam tubuh POST
Pemusnahan titik akhir yang ada
Pemusnahan metode permintaan titik akhir yang ada
Perilaku internal API yang sangat berbeda – seperti perubahan pada perilaku default.
Yang Besar 1.0
Seperti yang telah kami dokumentasikan dan diskusikan mengenai konvensi ini, kami juga sampai pada kesimpulan bahwa adalah demi kepentingan semua orang (termasuk kami!) untuk menghindari perubahan besar pada API karena mengelola beberapa versi menambah cukup banyak beban. Kami memutuskan bahwa ada beberapa hal yang harus kami perbaiki pada API kami sebelum berkomitmen pada “v1”.
Mengirim email sederhana memerlukan terlalu banyak usaha. Untuk “menjaga agar hal-hal sederhana tetap sederhana”, kami memperbarui badan POST untuk memastikan bahwa baik kasus penggunaan sederhana maupun kompleks bisa terakomodasi. Format baru juga lebih tahan masa depan. Selain itu, kami menangani masalah dengan endpoint Metrics. Endpoint ini menggunakan parameter “group_by” yang mengubah format badan respons GET sehingga kunci pertama menjadi nilai parameter group by. Itu tidak terlihat sangat RESTful, jadi kami memecah setiap group by menjadi endpoint terpisah. Akhirnya, kami melakukan audit pada setiap endpoint dan membuat perubahan kecil di sana-sini untuk memastikan bahwa mereka sesuai dengan standar.
Seperti yang telah kami dokumentasikan dan diskusikan mengenai konvensi ini, kami juga sampai pada kesimpulan bahwa adalah demi kepentingan semua orang (termasuk kami!) untuk menghindari perubahan besar pada API karena mengelola beberapa versi menambah cukup banyak beban. Kami memutuskan bahwa ada beberapa hal yang harus kami perbaiki pada API kami sebelum berkomitmen pada “v1”.
Mengirim email sederhana memerlukan terlalu banyak usaha. Untuk “menjaga agar hal-hal sederhana tetap sederhana”, kami memperbarui badan POST untuk memastikan bahwa baik kasus penggunaan sederhana maupun kompleks bisa terakomodasi. Format baru juga lebih tahan masa depan. Selain itu, kami menangani masalah dengan endpoint Metrics. Endpoint ini menggunakan parameter “group_by” yang mengubah format badan respons GET sehingga kunci pertama menjadi nilai parameter group by. Itu tidak terlihat sangat RESTful, jadi kami memecah setiap group by menjadi endpoint terpisah. Akhirnya, kami melakukan audit pada setiap endpoint dan membuat perubahan kecil di sana-sini untuk memastikan bahwa mereka sesuai dengan standar.
Seperti yang telah kami dokumentasikan dan diskusikan mengenai konvensi ini, kami juga sampai pada kesimpulan bahwa adalah demi kepentingan semua orang (termasuk kami!) untuk menghindari perubahan besar pada API karena mengelola beberapa versi menambah cukup banyak beban. Kami memutuskan bahwa ada beberapa hal yang harus kami perbaiki pada API kami sebelum berkomitmen pada “v1”.
Mengirim email sederhana memerlukan terlalu banyak usaha. Untuk “menjaga agar hal-hal sederhana tetap sederhana”, kami memperbarui badan POST untuk memastikan bahwa baik kasus penggunaan sederhana maupun kompleks bisa terakomodasi. Format baru juga lebih tahan masa depan. Selain itu, kami menangani masalah dengan endpoint Metrics. Endpoint ini menggunakan parameter “group_by” yang mengubah format badan respons GET sehingga kunci pertama menjadi nilai parameter group by. Itu tidak terlihat sangat RESTful, jadi kami memecah setiap group by menjadi endpoint terpisah. Akhirnya, kami melakukan audit pada setiap endpoint dan membuat perubahan kecil di sana-sini untuk memastikan bahwa 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 yang tidak sengaja. Kami memutuskan untuk menggunakan pendekatan dokumentasi API yang sederhana dengan memanfaatkan bahasa Markdown yang disebut API Blueprint dan mengelola dokumen kami di Github. Komunitas kami berkontribusi dan meningkatkan dokumentasi sumber terbuka ini. Kami juga memelihara satu set dokumen yang tidak dipublikasikan di Github untuk API dan endpoint internal.
Awalnya, kami menerbitkan dokumen kami ke Apiary, sebuah alat hebat untuk prototyping dan menerbitkan dokumen API. Namun, embedding Apiary ke dalam situs web kami tidak berfungsi di perangkat seluler, jadi sekarang kami menggunakan Jekyll untuk menghasilkan dokumen statis. Dokumentasi SparkPost API terbaru kami sekarang memuat dengan cepat dan bekerja dengan baik di perangkat seluler yang penting bagi pengembang yang tidak selalu berada di depan komputer mereka.
Adalah penting untuk memiliki dokumentasi API yang akurat dan dapat digunakan untuk menghindari perubahan yang merusak, baik yang disengaja maupun yang tidak sengaja. Kami memutuskan untuk menggunakan pendekatan dokumentasi API yang sederhana dengan memanfaatkan bahasa Markdown yang disebut API Blueprint dan mengelola dokumen kami di Github. Komunitas kami berkontribusi dan meningkatkan dokumentasi sumber terbuka ini. Kami juga memelihara satu set dokumen yang tidak dipublikasikan di Github untuk API dan endpoint internal.
Awalnya, kami menerbitkan dokumen kami ke Apiary, sebuah alat hebat untuk prototyping dan menerbitkan dokumen API. Namun, embedding Apiary ke dalam situs web kami tidak berfungsi di perangkat seluler, jadi sekarang kami menggunakan Jekyll untuk menghasilkan dokumen statis. Dokumentasi SparkPost API terbaru kami sekarang memuat dengan cepat dan bekerja dengan baik di perangkat seluler yang penting bagi pengembang yang tidak selalu berada di depan komputer mereka.
Adalah penting untuk memiliki dokumentasi API yang akurat dan dapat digunakan untuk menghindari perubahan yang merusak, baik yang disengaja maupun yang tidak sengaja. Kami memutuskan untuk menggunakan pendekatan dokumentasi API yang sederhana dengan memanfaatkan bahasa Markdown yang disebut API Blueprint dan mengelola dokumen kami di Github. Komunitas kami berkontribusi dan meningkatkan dokumentasi sumber terbuka ini. Kami juga memelihara satu set dokumen yang tidak dipublikasikan di Github untuk API dan endpoint internal.
Awalnya, kami menerbitkan dokumen kami ke Apiary, sebuah alat hebat untuk prototyping dan menerbitkan dokumen API. Namun, embedding Apiary ke dalam situs web kami tidak berfungsi di perangkat seluler, jadi sekarang kami menggunakan Jekyll untuk menghasilkan dokumen statis. Dokumentasi SparkPost API terbaru kami sekarang memuat dengan cepat dan bekerja dengan baik di perangkat seluler yang penting bagi pengembang yang tidak selalu berada di depan komputer mereka.
Memisahkan Penyebaran dari Rilis
Kami belajar sejak awal trik berharga untuk memisahkan penyebaran dari rilis. Dengan cara ini, mungkin untuk secara sering mengirimkan perubahan ketika mereka siap melalui pengiriman dan penyebaran berkelanjutan, tetapi kami tidak selalu mengumumkan atau mendokumentasikannya secara publik pada saat yang sama. Tidak jarang bagi kami untuk menyebarkan endpoint API baru atau peningkatan pada endpoint API yang sudah ada dan menggunakannya dari dalam UI atau dengan alat internal sebelum kami mendokumentasikannya secara publik dan mendukungnya. Dengan cara itu, kami dapat membuat beberapa penyesuaian untuk kegunaan atau kepatuhan terhadap standar tanpa khawatir tentang membuat perubahan yang tidak diinginkan. Setelah kami puas dengan perubahan tersebut, kami menambahkannya ke dokumentasi publik kami.
Kami belajar sejak awal trik berharga untuk memisahkan penyebaran dari rilis. Dengan cara ini, mungkin untuk secara sering mengirimkan perubahan ketika mereka siap melalui pengiriman dan penyebaran berkelanjutan, tetapi kami tidak selalu mengumumkan atau mendokumentasikannya secara publik pada saat yang sama. Tidak jarang bagi kami untuk menyebarkan endpoint API baru atau peningkatan pada endpoint API yang sudah ada dan menggunakannya dari dalam UI atau dengan alat internal sebelum kami mendokumentasikannya secara publik dan mendukungnya. Dengan cara itu, kami dapat membuat beberapa penyesuaian untuk kegunaan atau kepatuhan terhadap standar tanpa khawatir tentang membuat perubahan yang tidak diinginkan. Setelah kami puas dengan perubahan tersebut, kami menambahkannya ke dokumentasi publik kami.
Kami belajar sejak awal trik berharga untuk memisahkan penyebaran dari rilis. Dengan cara ini, mungkin untuk secara sering mengirimkan perubahan ketika mereka siap melalui pengiriman dan penyebaran berkelanjutan, tetapi kami tidak selalu mengumumkan atau mendokumentasikannya secara publik pada saat yang sama. Tidak jarang bagi kami untuk menyebarkan endpoint API baru atau peningkatan pada endpoint API yang sudah ada dan menggunakannya dari dalam UI atau dengan alat internal sebelum kami mendokumentasikannya secara publik dan mendukungnya. Dengan cara itu, kami dapat membuat beberapa penyesuaian untuk kegunaan atau kepatuhan terhadap standar tanpa khawatir tentang membuat perubahan yang tidak diinginkan. Setelah kami puas dengan perubahan tersebut, kami menambahkannya ke dokumentasi publik kami.
