TL;DR
Ruang kerja API Git-native berarti spesifikasi API Anda disimpan di Git sebagai sumber kebenaran, dengan kontrol versi penuh, percabangan, dan alur kerja permintaan penggabungan yang terintegrasi langsung ke dalam platform pengembangan API Anda. Tim bekerja di cabang sprint yang terisolasi, meninjau perubahan melalui permintaan penggabungan, dan melakukan sinkronisasi secara otomatis dengan repositori mereka. Mode Spec-first Apidog menghadirkan alur kerja ini dengan IDE bawaan untuk mengedit spesifikasi OpenAPI, validasi real-time, dan integrasi GitHub/GitLab/Azure DevOps yang mulus.
Mengapa Tim API Membutuhkan Alur Kerja Git-Native
Jujur saja. Setelah memimpin pengembangan API selama beberapa tahun, saya telah melihat masalah kolaborasi yang sama berulang di setiap tim:
- "Versi spec mana yang saat ini berlaku?" — Lima orang mengedit koleksi Postman yang sama, tidak ada yang tahu versi siapa yang otoritatif.
- "Mengapa endpoint ini berubah?" — Tidak ada changelog, tidak ada riwayat, tidak ada cara melacak mengapa parameter diganti namanya tiga bulan lalu.
- "Bisakah saya mengerjakan fitur baru tanpa merusak spec utama?" — Entah semua orang mengedit spec langsung bersamaan (kekacauan) atau Anda menduplikasi file dan menggabungkannya secara manual nanti (rawan kesalahan).
- "Bagaimana cara kami meninjau perubahan API ini?" — Mengirim cuplikan JSON di Slack, menempelkan tangkapan layar di Jira, tidak ada proses peninjauan terstruktur.
Kedengarannya familiar?
Ini bukan masalah alat. Ini adalah masalah alur kerja. Dan alur kerja yang menyelesaikan semua masalah ini? Ini adalah alur kerja yang sama yang sudah digunakan tim kode Anda: Git.
Insinyur backend Anda hidup di Git. Insinyur frontend Anda hidup di Git. Tim DevOps Anda hidup di Git. Namun entah bagaimana, desain API sering kali berada di luar dunia itu — terkunci dalam alat-alat proprietary, terisolasi dari sistem kontrol versi yang menggerakkan segalanya.
Itulah celah yang diisi oleh pendekatan Git-native Apidog. Ini membawa spesifikasi API Anda ke dalam alur kerja Git yang sama yang sudah dipercaya oleh seluruh organisasi rekayasa Anda.
Apa Arti "Git-Native" Sebenarnya untuk API?
Pengembangan API Git-native bukan hanya "menyimpan file OpenAPI Anda di repositori." Itu sudah mungkin dilakukan bertahun-tahun, dan tim masih menghadapi masalah kolaborasi yang sama.
Git-native sejati berarti:
| Penyimpanan Git Tradisional | Ruang Kerja Git-Native |
|---|---|
| Spesifikasi disimpan di Git, tetapi Anda mengeditnya di alat eksternal | Edit spesifikasi di dalam platform dengan Git sebagai sumber kebenaran |
| Commit manual setelah mengedit di tempat lain | Commit dan push langsung dari ruang kerja API |
| Tidak ada konsep percabangan API | Cabang sprint untuk pengembangan fitur yang terisolasi |
| Alat peninjauan kode canggung diterapkan pada diff YAML | Permintaan penggabungan bawaan yang dirancang untuk perubahan API |
| Sinkronisasi terputus ketika seseorang mengedit salinan internal alat | Sinkronisasi dua arah yang menghormati Git sebagai yang utama |
Perbedaannya adalah kedalaman integrasi. Ruang kerja API Git-native memperlakukan repositori Anda sebagai sumber otoritatif, bukan tujuan cadangan. Semuanya — mengedit, membuat cabang, meninjau, menguji — terjadi dengan Git di bawahnya.
Komponen Inti
- Mode Spec-first — File OpenAPI YAML/JSON Anda adalah artefak utama, bukan catatan database internal
- Cabang Sprint — Cabang fitur API yang bekerja seperti cabang Git untuk kode
- Cabang Utama Terlindungi — Stabilitas produksi melalui alur kerja peninjauan yang diberlakukan
- Permintaan Penggabungan — Peninjauan perubahan API terstruktur dengan perbandingan sebelum/sesudah
- Sinkronisasi Webhook — Sinkronisasi otomatis saat repositori Anda menerima push
Ini bukan konsep baru. Ini adalah penerapan alur kerja Git yang terbukti ke domain yang sudah membutuhkannya bertahun-tahun yang lalu.
Masalah dengan Alat API Tradisional
Sebagian besar platform pengembangan API beroperasi dengan model database internal:
- Anda membuat endpoint melalui formulir visual
- Platform menyimpan semuanya dalam databasenya sendiri
- Ekspor ke OpenAPI saat dibutuhkan (seringkali tidak lengkap atau usang)
- Jika Anda menginginkan riwayat Git, Anda mengekspor secara manual dan melakukan commit sendiri
Model ini bekerja dengan baik untuk individu. Tapi untuk tim? Ini menciptakan friksi mendasar:
Tidak Ada Riwayat Versi Sejati
Platform mungkin memiliki "riwayat," tetapi itu bukan riwayat Git. Anda tidak bisa:
- Melihat siapa mengubah apa dan kapan dalam changelog terpadu
- Membuat cabang dan menggabungkan dengan bersih
- Mengembalikan ke keadaan yang diketahui menggunakan perintah Git standar
- Menggunakan pipeline CI/CD yang mengharapkan alur kerja yang dipicu Git
Konflik Kolaborasi
Ketika beberapa pengembang mengedit proyek yang sama:
- Perubahan dapat menimpa satu sama lain tanpa peringatan
- Tidak ada mekanisme resolusi konflik penggabungan
- Pengeditan "langsung" berarti tidak ada isolasi untuk fitur baru
Kesenjangan Peninjauan
Bagaimana cara Anda meninjau perubahan API? Dalam alat tradisional:
- Tangkapan layar UI
- Cuplikan JSON yang diekspor ditempelkan ke dokumen
- Tidak ada tampilan diff terstruktur
- Tidak ada alur kerja persetujuan dengan jejak audit
Diskoneksi
Spesifikasi API Anda menjelaskan kontrak antar sistem. Ini sama pentingnya dengan kode aplikasi Anda. Namun ia hidup di luar sistem kontrol versi yang melindungi segalanya. Diskoneksi itulah akar penyebab sebagian besar masalah kolaborasi API.
Pendekatan Git-Native Apidog: Mode Spec-first
Mode Spec-first Apidog membalik model: Git menjadi sumber kebenaran, dan platform menjadi antarmuka Anda dengannya.
Bagaimana Cara Kerjanya
Ketika Anda membuat proyek Spec-first, Apidog terhubung langsung ke repositori Anda:
- Hubungkan penyedia Git Anda — GitHub, GitLab, Azure DevOps, atau Bitbucket
- Pilih repositori dan cabang utama Anda — Apidog membaca spesifikasi yang ada atau memulai dari awal
- Edit di ruang kerja Specs — Tampilan kode dengan penyorotan sintaks, atau tampilan formulir untuk pengeditan terstruktur
- Commit & Push dari Apidog — Perubahan langsung masuk ke repositori Anda
- Sinkronisasi Webhook menjaga kedua sisi tetap selaras — Push ke Git secara otomatis disinkronkan kembali ke Apidog
Ruang Kerja Specs
Di sinilah pengalaman Git-native bersinar. Daripada mengisi formulir yang memperbarui database internal, Anda bekerja dengan file:
- Penjelajah file — Jelajahi struktur repositori Anda secara langsung
- Pohon struktur API — Konten OpenAPI yang diurai: endpoint, skema, definisi
- Editor kode — Pengalaman IDE penuh dengan validasi, pelengkapan otomatis, penyorotan sintaks
- Editor formulir — Untuk node yang didukung, edit melalui kontrol terstruktur sementara file tetap menjadi sumber
Anda bisa bekerja sepenuhnya di YAML/JSON jika itu preferensi Anda. Atau beralih ke tampilan formulir untuk definisi endpoint yang kompleks. Bagaimanapun, file yang mendasari di Git adalah yang paling penting.
Validasi dan Pratinjau Real-Time
Editor mencakup:
- Panel validasi — Kesalahan sintaks, bidang wajib yang hilang, pelanggaran aturan OpenAPI segera terdeteksi
- Panel pratinjau — Lihat bagaimana spesifikasi Anda dirender sebagai dokumentasi sebelum melakukan commit
- Coba — Uji endpoint langsung dari definisi spesifikasi
Tidak ada lagi commit spesifikasi yang rusak dan menemukan kesalahan di CI.
Cabang Sprint: Cabang Fitur API Anda
Dalam pengembangan kode, cabang fitur tidak bisa dinegosiasikan. Anda tidak akan mengedit kode produksi secara langsung. Mengapa mengedit spesifikasi API produksi secara langsung?
Cabang sprint Apidog membawa isolasi yang sama ke pekerjaan API.
Yang Diaktifkan oleh Cabang Sprint
| Skenario | Tanpa Cabang Sprint | Dengan Cabang Sprint |
|---|---|---|
| Mengembangkan endpoint baru | Edit spesifikasi utama, berisiko merusak dokumentasi dan pengujian untuk semua orang | Bekerja secara terisolasi, gabungkan saat stabil |
| Menguji perubahan API | Semua penguji melihat pekerjaan yang belum selesai | Penguji dapat beralih ke cabang sprint untuk pengujian terfokus |
| Pengembangan fitur paralel | Beberapa fitur bertabrakan dalam satu spesifikasi | Setiap fitur memiliki cabangnya sendiri |
| Menggulirkan kembali perubahan | Tidak ada mekanisme pengguliran kembali yang bersih | Hapus atau gabungkan perubahan selektif |
Membuat Cabang Sprint
- Klik tombol cabang di sebelah API
- Pilih Cabang Sprint Baru
- Berikan nama untuk fitur Anda (misalnya,
user-authentication-v2) - Bekerja terisolasi dari cabang utama
Dua Cara Mengisi Cabang Sprint
Pendekatan manual (API-first):
Gunakan Fork dari utama untuk menyalin endpoint, skema, atau komponen yang perlu Anda modifikasi. Apidog melacak asosiasinya, sehingga penggabungan nanti akan tahu sumber daya mana yang berubah.
Pendekatan impor OAS (code-first):
Impor spesifikasi OpenAPI yang diperbarui dari backend Anda. Apidog membandingkannya dengan cabang utama dan hanya menarik sumber daya yang diubah. Ini membuat cabang sprint Anda fokus pada perbedaan aktual.
Pencocokan Pengujian Otomatis
Ada satu hal yang sebagian besar tim lewatkan: ketika Anda mengubah endpoint di cabang sprint, pengujian yang ada masih menargetkan versi cabang utama.
Apidog menyelesaikannya dengan:
- Menandai endpoint yang dimodifikasi dalam skenario pengujian Anda
- Membiarkan penguji menduplikasi dan menyesuaikan pengujian untuk versi cabang sprint
- Memastikan pengujian cocok dengan cabang yang sedang Anda kerjakan
Ini mencegah kegagalan umum: menggabungkan endpoint baru tanpa memperbarui pengujian, lalu menemukan pipeline CI yang rusak beberapa hari kemudian.
Cabang Terlindungi dan Permintaan Penggabungan
Cabang terlindungi adalah tulang punggung stabilitas produksi. Di Apidog, cabang utama yang terlindungi berarti:
- Tidak ada pengeditan langsung — Perubahan harus melalui permintaan penggabungan
- Peninjauan wajib — Administrator menyetujui sebelum penggabungan
- Jejak audit — Setiap perubahan memiliki catatan peninjauan
Alur Kerja Permintaan Penggabungan
Ketika pekerjaan cabang sprint Anda siap:
- Klik Gabungkan di tombol cabang
- Tinjau semua perubahan dengan status berkode warna:
- Abu-abu — tidak berubah (tidak perlu digabungkan)
- Oranye — dimodifikasi (bandingkan dengan cabang utama)
- Hijau — baru (dibuat di cabang sprint)
- Untuk sumber daya yang dimodifikasi, lihat diff yang tepat antara versi sprint dan utama
- Pilih apa yang akan digabungkan
- Buat Permintaan Penggabungan (untuk cabang terlindungi) atau Gabungkan langsung (tidak terlindungi)
Proses Peninjauan
Peninjau melihat:
- Daftar perubahan lengkap
- Perbandingan sebelum/sesudah untuk setiap sumber daya yang dimodifikasi
- Konteks dari cabang sprint
Mereka dapat menyetujui, menolak, atau meminta modifikasi. Jika pengembang memperbarui cabang sprint, permintaan penggabungan secara otomatis mencerminkan perubahan baru — tidak perlu membuat permintaan baru.
Ini adalah alur kerja peninjauan yang telah dibutuhkan tim API selama bertahun-tahun. Tidak ada lagi peninjauan berbasis tangkapan layar, tidak ada lagi utas Slack yang mencoba menjelaskan perubahan endpoint.
Integrasi Git Tanpa Batas: Commit, Push, Pull
Operasi Git terjadi langsung di dalam Apidog. Tidak diperlukan klien Git eksternal.
Commit & Push
Setelah mengedit:
- Klik Perubahan untuk meninjau file yang dimodifikasi, ditambahkan, dihapus
- Pilih file untuk disertakan
- Tulis pesan commit
- Klik Push — perubahan langsung disinkronkan ke repositori Anda
Git Pull
Ketika rekan tim mendorong perubahan ke repositori yang terhubung:
- Klik nama cabang di bilah sisi Specs
- Pilih Git Pull — file terbaru disinkronkan ke Apidog
Sinkronisasi Webhook (Direkomendasikan)
Jika Anda memiliki akses admin repositori, instal webhook selama penyiapan:
- Push ke repositori Anda memicu sinkronisasi Apidog otomatis
- Tidak perlu pull manual
- Tim tetap selaras tanpa usaha
Tanpa sinkronisasi webhook, pull manual tetap berfungsi dengan baik. Namun sinkronisasi webhook sepenuhnya menghilangkan pertanyaan "siapa yang memiliki spesifikasi terbaru?".
Apa yang Berubah vs Alur Kerja Tradisional
| Sebelum | Sesudah |
|---|---|
| Pengembang mengedit spesifikasi utama secara langsung | Cabang sprint yang terisolasi |
| Penguji tidak dapat menguji perubahan yang belum selesai | Cabang khusus untuk pengujian |
| Peninjauan melalui tangkapan layar dan utas Slack | Permintaan penggabungan terstruktur dengan diff |
| Tidak ada visibilitas ke pekerjaan paralel | Tombol cabang menunjukkan semua pekerjaan aktif |
| Penggabungan menimpa secara diam-diam | Penggabungan selektif dengan pratinjau |
Ini bukan menambah kompleksitas. Ini menambah struktur yang menghilangkan kekacauan.
FAQ
Apa perbedaan antara Mode Spec-first dan proyek Apidog reguler?
Mode Spec-first menggunakan repositori Git Anda sebagai sumber kebenaran. Proyek Apidog reguler menggunakan database internal Apidog sebagai yang utama, dengan ekspor Git sebagai sekunder. Dalam Mode Spec-first, Anda mengedit file secara langsung, melakukan commit ke Git dari Apidog, dan menyinkronkan secara otomatis. Dalam mode reguler, Anda mengedit melalui formulir, dan ekspor Git bersifat manual atau terjadwal.
Bisakah saya beralih proyek Apidog yang sudah ada ke Mode Spec-first?
Saat ini, Mode Spec-first memerlukan pembuatan proyek baru yang terhubung ke repositori Git. Anda dapat mengimpor spesifikasi OpenAPI proyek Anda yang sudah ada ke proyek Spec-first baru untuk memigrasi konten.
Penyedia Git mana yang didukung?
Apidog mendukung GitHub, GitLab, Azure DevOps, dan Bitbucket untuk proyek Spec-first. Anda dapat menghubungkan repositori dari salah satu penyedia ini selama pembuatan proyek.
Apakah saya memerlukan izin admin pada repositori saya?
Izin admin diperlukan untuk instalasi webhook, yang memungkinkan sinkronisasi otomatis saat repositori Anda menerima push. Tanpa sinkronisasi webhook, Anda masih dapat menggunakan Git Pull manual untuk menyinkronkan perubahan. Izin tulis sudah cukup untuk mendorong perubahan dari Apidog.
Bisakah saya menggunakan Mode Spec-first dengan repositori kosong?
Ya. Jika repositori Anda tidak memiliki file OpenAPI yang ada, Apidog akan memulai dari awal. Anda membuat spesifikasi di ruang kerja Specs dan mendorongnya ke repositori Anda. Commit pertama akan membentuk dasar spesifikasi Anda.
Bagaimana perbedaan cabang sprint dari cabang Git?
Cabang sprint di Apidog sesuai dengan cabang Git di repositori Anda. Ketika Anda membuat cabang sprint di Apidog, itu akan membuat cabang yang sesuai di Git. Perubahan dalam cabang sprint akan disinkronkan ke cabang Git tersebut. Penggabungan cabang sprint akan menggabungkan cabang Git yang sesuai.
Apa yang terjadi jika seseorang mengedit repositori Git secara langsung?
Jika sinkronisasi webhook diinstal, push ke Git akan memicu sinkronisasi otomatis ke Apidog. Jika Anda bekerja di Apidog dan seseorang mendorong ke Git, Anda akan melihat status sinkronisasi yang menunjukkan pembaruan yang tertunda. Gunakan Git Pull untuk membawa perubahan tersebut ke Apidog.
Bisakah saya mengedit spesifikasi dalam tampilan kode dan tampilan formulir?
Ya. Ruang kerja Specs mencakup editor kode untuk pengeditan YAML/JSON langsung, dan tampilan formulir untuk node OpenAPI yang didukung (endpoint, skema, definisi). Anda dapat beralih antar tampilan sesuai kebutuhan. Keduanya memperbarui file yang mendasari di Git.
Bagaimana cara kerja permintaan penggabungan untuk skenario pengujian?
Skenario pengujian digabungkan secara terpisah dari endpoint dan skema. Setelah menggabungkan sumber daya API ke cabang utama, arahkan kursor ke skenario pengujian di cabang sprint dan pilih Gabungkan ke Utama. Saat ini, hanya administrator proyek yang dapat menggabungkan skenario pengujian ke cabang utama yang dilindungi.