Apiary akan ditutup. Oracle telah memposting pengumuman penghentian dukungan Apiary, dan laporan dari berbagai sumber di bidang perkakas API menunjukkan penutupan akhir layanan yang di-host sekitar September 2026. Situs ini masih dapat diakses hari ini, namun perkembangannya sudah terlihat selama bertahun-tahun: Oracle mengakuisisi Apiary pada Januari 2017, menghentikan paket berbayar pada tahun 2018, dan membiarkan alat sumber terbuka di sekitarnya—Dredd dan Gavel—berstatus arsip. Jika dokumentasi API Anda berada di apiary.io, Anda tidak lagi sekadar mengevaluasi alternatif. Anda sedang bermigrasi, dan tenggat waktunya tidak dapat diubah.
Jawaban langsungnya: Apidog adalah alternatif Apiary terbaik karena menggantikan alur kerja inti Apiary—pengeditan spesifikasi berbasis desain, dokumentasi interaktif yang di-host, dan server tiruan—serta menambahkan pengujian API otomatis, validasi berbasis spesifikasi sebagai pengganti Dredd yang telah diarsipkan, dan integrasi CI. Apidog gratis hingga 4 pengguna, dengan paket berbayar mulai dari $9 per pengguna per bulan.
Satu batasan penting: Apidog tidak mengimpor API Blueprint secara langsung. Jika proyek Anda berbasis Blueprint, konversikan sekali ke OpenAPI sebelum mengimpor. Artikel ini membahas apa yang terjadi pada Apiary, langkah migrasi praktis, dan pilihan lain jika Apidog tidak sesuai.
Apa yang sebenarnya terjadi pada Apiary
Apiary, didirikan pada 2011, mempopulerkan alur kerja API berbasis desain. Platform ini memperkenalkan API Blueprint, format deskripsi API berbasis Markdown yang muncul sebelum OpenAPI menjadi populer. Apiary juga menawarkan dokumentasi tiga kolom, server tiruan yang di-host, sinkronisasi GitHub, serta alat pengujian kontrak sumber terbuka seperti Dredd dan Gavel.
Setelah Oracle mengakuisisi Apiary pada Januari 2017, produk ini memasuki periode tanpa banyak pengembangan. Paket berbayar dihentikan pada 2018, fitur baru berhenti berkembang, dan Dredd serta Gavel diarsipkan. Kini Oracle telah mengumumkan penghentian dukungan, dengan layanan yang di-host diperkirakan berakhir sekitar September 2026.
Bump.sh, salah satu vendor yang menerbitkan panduan migrasi, menyampaikan hal ini secara jelas: ekspor deskripsi API Anda sebelum layanan ditutup. Setelah itu, tidak ada lagi yang dapat diekspor.
Implikasinya praktis:
- Pindahkan semua aset yang hanya ada di Apiary sekarang: spesifikasi, prosa dokumentasi, dan konfigurasi tim.
- Gunakan OpenAPI sebagai format tujuan. API Blueprint tidak lagi memiliki ekosistem alat penerus yang aktif dipelihara.
Apa yang perlu Anda gantikan
Sebelum memilih platform baru, petakan fungsi Apiary yang digunakan tim Anda:
Editor spesifikasi berbasis desain
Anda menulis API Blueprint—atau OpenAPI 3.0 pada proyek yang lebih baru—di browser dan dokumentasi diperbarui langsung.Dokumentasi interaktif yang di-host
Referensi API tiga kolom dengan contoh permintaan, tersedia melalui URL apiary.io.Server tiruan
Setiap proyek Apiary memiliki endpoint tiruan yang di-host agar konsumen API dapat melakukan integrasi sebelum backend selesai.Sinkronisasi GitHub
File spesifikasi disimpan di repositori dan disinkronkan dua arah.Pengujian kontrak melalui Dredd
Dredd menjalankan spesifikasi terhadap implementasi API nyata lalu melaporkan penyimpangan. Karena Dredd kini diarsipkan, Anda memerlukan pengganti yang aktif dipelihara. Lihat juga cara memvalidasi API terhadap spesifikasinya tanpa Dredd.
Target migrasi yang baik harus mencakup desain, dokumentasi, mocking, dan validasi—bukan hanya merender dokumentasi.
Jawabannya: Apidog
Apidog adalah platform pengembangan API yang digunakan oleh lebih dari 500.000 pengembang. Platform ini mencakup desain, dokumentasi, pembuatan mock, debugging, dan pengujian otomatis yang digerakkan oleh satu spesifikasi.
Untuk migrasi dari Apiary, berikut pemetaannya:
Alur kerja design-first
Apidog menyediakan editor visual dan editor kode untuk OpenAPI 3.x. Definisikan endpoint, skema, dan contoh satu kali; dokumentasi, mock, dan pengujian menggunakan definisi yang sama.Dokumentasi di-host dan interaktif
Dokumentasi yang dipublikasikan memiliki tata letak referensi modern, konsol “coba” yang berfungsi, domain kustom, dan versi. Anda tidak lagi bergantung pada URLapiary.io.Mock server berbasis skema
Server mock Apiary memutar ulang contoh yang Anda tulis. Mock server pintar Apidog dapat menghasilkan respons dari skema, tanpa selalu membutuhkan contoh manual. Anda juga dapat menambahkan aturan mock khusus ketika respons harus deterministik.Validasi kontrak sebagai pengganti Dredd
Skenario pengujian otomatis Apidog menjalankan permintaan nyata terhadap implementasi Anda lalu memvalidasi respons terhadap skema spesifikasi. Anda dapat menambahkan assertion, kasus berbasis data, serta menjalankannya di CI dengan Apidog CLI. Dokumentasi juga dapat dipublikasikan bersama server MCP agar agen AI dapat membaca spesifikasi secara langsung. Pelajari lebih lanjut di apa itu Apidog MCP Server.
Bermigrasi dari Apiary, langkah demi langkah
Migrasi dari Apiary memiliki satu langkah tambahan: konversi API Blueprint ke OpenAPI.
Menurut dokumentasi impor Apidog, Apidog mendukung impor:
- Swagger 2.0
- OpenAPI 3.0 dan 3.1
- Koleksi Postman
- HAR
- RAML
- JMeter
- apiDoc
- I/O Docs
- WADL
- Google Discovery
API Blueprint tidak ada dalam daftar tersebut. Jadi, konversikan Blueprint ke OpenAPI terlebih dahulu.
1. Ekspor semuanya dari Apiary sekarang
Untuk setiap proyek:
- Unduh deskripsi API dari editor Apiary.
- Jika proyek terhubung ke GitHub, pastikan file di repositori adalah versi terbaru.
- Identifikasi proyek yang sudah menggunakan OpenAPI 3.0—proyek tersebut dapat langsung melewati langkah konversi.
- Simpan hasil ekspor di repositori atau penyimpanan yang dikelola tim.
Lakukan langkah ini sebelum mulai mengevaluasi alat lain. Ekspor adalah bagian migrasi yang memiliki tenggat waktu.
2. Konversi API Blueprint ke OpenAPI
Gunakan salah satu alat berikut:
-
api-spec-converterdari LucyBot untuk konversi API Blueprint ke OpenAPI -
apib2swaggeruntuk konversi Blueprint ke Swagger/OpenAPI -
openapi-formatsetelah konversi jika Anda ingin menormalkan output atau meng-upgrade ke OpenAPI 3.1
Contoh alur kerja:
# Konversi file Blueprint ke format OpenAPI/Swagger
api-spec-converter api.apib --from api_blueprint --to openapi_3 --syntax yaml > openapi.yaml
# Format dan normalisasi hasilnya bila diperlukan
openapi-format openapi.yaml --output openapi-formatted.yaml
Setelah konversi:
- Jalankan linter atau validator, misalnya
vacuum. - Periksa skema autentikasi secara manual.
- Periksa prosa Markdown yang sebelumnya berada di luar deskripsi endpoint Blueprint.
- Pastikan contoh respons, parameter, dan kode status tetap sesuai dengan implementasi API.
Dua area yang paling perlu diperiksa adalah autentikasi dan dokumentasi naratif. API Blueprint tidak memodelkan autentikasi secara formal, sehingga konverter tidak selalu dapat memulihkannya sepenuhnya.
Untuk banyak API, konversi ini dapat diselesaikan sekitar satu jam per API, bukan berminggu-minggu.
3. Impor ke Apidog
Di Apidog:
- Buka Pengaturan Proyek.
- Pilih Impor Manual.
- Pilih file OpenAPI hasil konversi, atau impor dari URL.
- Tinjau endpoint, skema, parameter, dan contoh yang dihasilkan.
- Publikasikan dokumentasi jika sudah siap.
Setelah impor, dokumentasi referensi langsung tersedia. Mock server pintar juga aktif untuk endpoint yang diimpor tanpa konfigurasi tambahan.
4. Bangun kembali bagian yang tidak dapat dilakukan Apiary
Setelah spesifikasi berhasil diimpor:
Gunakan domain kustom untuk dokumentasi
Hindari ketergantungan pada URL platform. Dengan domain kustom, perubahan vendor tidak akan memutus URL dokumentasi publik Anda.-
Buat ulang pemeriksaan Dredd
Buat skenario pengujian dengan:- permintaan nyata ke environment API,
- validasi respons terhadap skema OpenAPI,
- assertion untuk status, header, dan body,
- data-driven test bila diperlukan.
Jalankan pengujian di CI
Jalankan skenario melalui CLI agar validasi kontrak menjadi bagian dari pipeline build atau deployment.Komunikasikan URL mock baru
Jika konsumen API menggunakan endpoint mock Apiary, kirim URL dasar mock baru bersama pengumuman perpindahan dokumentasi.
Satu proyek API dapat dipindahkan dalam satu sore, termasuk konversi. Portofolio dengan banyak API Blueprint biasanya membutuhkan satu sprint, terutama untuk pemeriksaan autentikasi secara manual.
Apiary vs Apidog sekilas
| Apiary (hari ini) | Apidog | |
|---|---|---|
| Masa depan | Akan ditutup; dukungan dihentikan, layanan diperkirakan berakhir sekitar September 2026 | Dikembangkan secara aktif |
| Format spesifikasi | API Blueprint, kemudian OpenAPI 3.0 | OpenAPI 3.x, impor Swagger 2.0, editor visual dan kode |
| Dokumentasi di-host | Ya, pada URL apiary.io | Ya, domain kustom, versi, dan konsol coba |
| Mock server | Memutar ulang contoh yang ditulis | Mock pintar berbasis skema dan aturan khusus |
| Pengujian kontrak | Dredd, kini diarsipkan | Skenario pengujian bawaan, validasi skema, CI melalui CLI |
| Suite pengujian otomatis | Tidak | Ya, skenario visual, berbasis data, dan jalankan tak terbatas |
| Sinkronisasi GitHub | Ya | Impor atau sinkronisasi spesifikasi dari URL atau file; versi berbasis cabang |
| Harga | Gratis; paket berbayar dihentikan pada 2018 | Gratis hingga 4 pengguna, lalu $9 per pengguna per bulan |
| Jalur ekspor | Unduhan API Blueprint atau OpenAPI | Ekspor OpenAPI, Markdown, dan HTML |
Berapa biaya mengganti alat gratis
Apiary gratis, jadi bandingkan biaya tahunan tujuan migrasi berdasarkan harga daftar:
| Ukuran tim | Apidog per tahun | SwaggerHub Team per tahun | ReadMe Pro per tahun |
|---|---|---|---|
| 3 orang | $0, paket gratis | $1.240 | $3.000 |
| 5 orang | $540 | $2.066 | $3.000 |
| 10 orang | $1.080 | $4.133 | $3.000 |
| 25 orang | $2.700 | $10.332 | $3.000 |
Jika Anda hanya membutuhkan renderer dokumentasi gratis untuk satu spesifikasi, alat khusus dokumentasi dengan paket gratis mungkin cukup. Namun, tabel ini relevan ketika Anda membutuhkan mock server, pengujian, dan kolaborasi—fitur yang membuat Apiary berguna sejak awal.
Paket gratis Apidog mencakup fitur tersebut hingga 4 pengguna. Bagi banyak tim yang bermigrasi dari Apiary, biaya utama migrasi hanya waktu untuk konversi.
Jika Apidog bukan pilihan yang tepat
Tidak semua tim membutuhkan platform dengan cakupan penuh. Pertimbangkan alternatif berikut berdasarkan kebutuhan Anda:
Anda hanya membutuhkan rendering dokumentasi
Jika spesifikasi diproduksi dan diuji di tempat lain, produk yang fokus pada dokumentasi seperti Bump.sh dapat menjadi pilihan yang masuk akal. Anda tetap perlu mengonversi API Blueprint ke OpenAPI.Anda menstandarkan pada ekosistem SmartBear
SwaggerHub adalah penerus filosofis terdekat untuk registry spesifikasi yang di-host. Perhatikan biaya per pengguna dan eksekusi pengujian berbayar. Lihat alternatif SwaggerHub terbaik.Anda fokus pada tata kelola desain untuk tim platform besar
Stoplight menyediakan panduan gaya dan tata kelola yang mendalam. Bandingkan kebutuhan Anda melalui alternatif Stoplight terbaik.Anda ingin tetap menggunakan API Blueprint
Sebaiknya jangan. Alat untuk format ini tidak lagi dipelihara, perusahaan yang membuatnya akan menghentikan layanannya, dan OpenAPI telah menjadi standar dominan. Konversikan sekali, lalu lanjutkan dengan OpenAPI. Panduan API Blueprint dapat tetap berguna sebagai referensi sejarah.
Pertanyaan yang sering diajukan
Kapan tepatnya Apiary ditutup?
Oracle telah mengumumkan penghentian dukungan Apiary di forumnya. Laporan terkini dari vendor alat API menunjukkan penutupan layanan yang di-host sekitar September 2026. Langkah paling aman adalah mengekspor sekarang karena produk ini sudah tidak lagi dipelihara.
Bisakah Apidog mengimpor file API Blueprint secara langsung?
Tidak. Apidog mengimpor OpenAPI/Swagger, Postman, HAR, RAML, JMeter, apiDoc, I/O Docs, WADL, dan Google Discovery. Konversikan API Blueprint ke OpenAPI terlebih dahulu dengan alat seperti api-spec-converter atau apib2swagger, lalu impor hasilnya. Periksa skema autentikasi secara manual setelah konversi.
Apa yang menggantikan mock server Apiary?
Mock server pintar bawaan Apidog. Apiary memutar ulang contoh yang Anda tulis, sedangkan Apidog dapat menghasilkan respons dari skema secara otomatis. Anda juga dapat membuat aturan mock khusus untuk kasus tertentu. Setiap endpoint yang diimpor mendapatkan endpoint mock tanpa konfigurasi tambahan.
Apa yang menggantikan Dredd untuk pengujian kontrak?
Skenario pengujian otomatis Apidog. Skenario ini mengirim permintaan nyata ke implementasi API dan memvalidasi respons terhadap skema spesifikasi. Anda dapat menambahkan assertion dan menjalankannya di CI melalui Apidog CLI. Ini mencakup fungsi Dredd serta fitur suite pengujian yang tidak dimiliki Dredd.
Apakah Apidog benar-benar gratis untuk tim kecil?
Ya. Paket gratis mencakup hingga 4 pengguna, editor spesifikasi, dokumentasi interaktif yang dipublikasikan, mock server pintar, dan pengujian API. Di atas 4 pengguna, biayanya $9 per pengguna per bulan.
Ekspor hari ini, jangan mendesain ulang apa pun
Urutan kerja migrasi sangat penting:
- Ekspor dari Apiary.
- Konversikan API Blueprint ke OpenAPI.
- Evaluasi dan pilih tujuan migrasi.
- Impor spesifikasi.
- Publikasikan dokumentasi, aktifkan mock, dan buat pengujian kontrak.
Dua langkah pertama memiliki tenggat waktu. Evaluasi platform dapat dilakukan setelah aset Anda aman.
Saat siap, impor file OpenAPI Anda ke Apidog untuk mendapatkan dokumentasi, mock server, dan alat pengujian dalam satu platform. Unduh Apidog atau mulai melalui browser. Tim hingga 4 orang tidak membayar apa pun, sementara alur kerja berbasis desain yang dipopulerkan Apiary dapat dilanjutkan di platform yang aktif dipelihara.
Top comments (0)