Dalam proyek Apidog, titik akhir (endpoints) dikelola dalam struktur hierarkis Module → Folder → Endpoints.
- Modul merepresentasikan file OpenAPI independen, biasanya dikelompokkan berdasarkan domain bisnis atau layanan.
- Folder mengatur titik akhir berdasarkan fitur atau fungsi dalam sebuah modul.
- Titik akhir (Endpoints) adalah spesifikasi OpenAPI atau definisi API yang sebenarnya.
Memahami struktur ini adalah kunci untuk mengelola API Anda secara efisien.
Berikut adalah contoh hierarki sederhana:
Proyek Apidog
│
├── Modul: Layanan Pengguna (dibagi berdasarkan domain bisnis atau layanan)
│ │
│ ├── Folder: Autentikasi Pengguna (kategori fitur)
│ │ │
│ │ ├── Titik Akhir: POST /login (Login)
│ │ └── Titik Akhir: POST /register (Daftar)
│ │
│ └── Folder: Info Pengguna
│ │
│ └── Titik Akhir: GET /users/{id} (Dapatkan Info Pengguna)
│
└── Modul: Layanan Pesanan
│
├── Folder: Manajemen Pesanan
│ │
│ ├── Titik Akhir: POST /orders (Buat Pesanan)
│ └── Titik Akhir: GET /orders/{id} (Dapatkan Detail Pesanan)
│
└── Folder: Pembayaran
│
└── Titik Akhir: POST /payment/submit (Kirim Pembayaran)Memahami Modul di Apidog
Setelah memahami hierarki proyek, pertanyaan selanjutnya adalah: Apakah setiap proyek membutuhkan modul? Kapan Anda harus membuat yang baru?
Saat Anda membuat proyek baru, Apidog secara otomatis menghasilkan modul default. Jika proyek Anda hanya berisi satu layanan backend atau sejumlah kecil titik akhir, modul default ini biasanya sudah cukup. Namun, jika Anda perlu mengelola beberapa layanan API yang berbeda, Anda dapat membuat modul terpisah untuk setiap layanan.
Misalnya, backend proyek mungkin mencakup layanan seperti Pengguna, Produk, Pesanan, dan Logistik—masing-masing bertanggung jawab atas domain tertentu dan seringkali di-deploy pada URL layanan yang berbeda. Dalam kasus ini, disarankan untuk membuat modul individual untuk layanan-layanan ini guna mengelola titik akhirnya secara independen.
Anda dapat membuat modul dengan mengklik tombol + di atas pohon folder dan memilih Module.
Setelah dibuat, modul tersebut akan muncul di pohon proyek sisi kiri bersama yang lain, dengan ruangnya sendiri untuk folder dan titik akhir. Anda dapat dengan bebas menambahkan titik akhir dan folder di dalam setiap modul.
Modul bersifat independen satu sama lain, masing-masing dengan titik akhir, skema, komponen, dan variabel modulnya sendiri. Namun, skema dapat direferensikan di seluruh modul. Selain itu, pengaturan tingkat proyek seperti variabel lingkungan, koneksi database, dan skrip umum dapat diakses oleh semua modul.
Setiap modul sesuai dengan file spesifikasi OpenAPI lengkap. Saat mengekspor proyek Anda, file OpenAPI dihasilkan per modul.
Memahami Folder dalam Sebuah Modul
Setelah membuat modul Anda, langkah selanjutnya adalah merencanakan bagaimana menyusun titik akhir di dalamnya.
Setiap modul dimulai dengan folder root yang menampung semua subfolder dan titik akhir.
Anda dapat membuat folder langsung di bawah root atau menumpuknya di dalam folder lain yang sudah ada.
Saat merancang struktur folder, pertimbangkan seberapa kompleks modul tersebut. Untuk modul dengan hanya beberapa titik akhir, folder satu tingkat sederhana yang diatur berdasarkan fungsi biasanya sudah cukup. Namun untuk modul yang lebih kompleks, lebih baik membuat folder multi-tingkat yang terstruktur dengan baik agar semuanya tetap terorganisir dan mudah dinavigasi.
Misalnya, dalam modul Layanan Pengguna, Anda mungkin memiliki folder tingkat atas seperti:
- Autentikasi Pengguna (untuk titik akhir login, pendaftaran, reset kata sandi)
- Info Pengguna
- Kontrol Akses
Jika satu folder menjadi terlalu besar atau secara logis independen, Anda dapat mengubahnya menjadi modul mandiri.
Klik ikon ... di samping nama folder dan pilih ...Lainnya > Konversi ke Modul baru. Ini membantu menjaga struktur proyek Anda tetap terorganisir dengan baik seiring skalanya.
Manajemen Lingkungan & Konfigurasi untuk Sebuah Modul
Selain titik akhir yang terstruktur, setiap modul biasanya sesuai dengan alamat layanan atau lingkungan deployment yang berbeda. Anda dapat mengkonfigurasi ini dengan mudah di Manajemen Lingkungan.
Dalam pengaturan manajemen lingkungan, Base URL setiap modul dapat dikonfigurasi secara terpisah. Misalnya, dalam Lingkungan Pengujian:
- Layanan Pengguna →
http://user-service:8001 - Layanan Pesanan →
http://order-service:8002
Saat beralih lingkungan, Apidog secara otomatis memperbarui Base URL setiap modul. Misalnya, saat beralih lingkungan pengembangan ke lingkungan pengujian, Base URL modul layanan pengguna akan berubah dari http://localhost:8001 menjadi http://user-service:8001, dan Base URL modul layanan pesanan akan berubah dari http://localhost:8002 menjadi http://order-service:8002.
Variabel lingkungan dibagikan di seluruh modul dan paling baik digunakan untuk menyimpan pengaturan yang berbeda antar lingkungan. Sebaliknya, variabel modul bersifat unik untuk setiap modul — misalnya, kunci API atau token mereka sendiri — dan dapat digunakan di titik akhir mana pun dalam modul tersebut.
Mengelola dan Menggunakan Kembali Skema
Manajemen skema yang efisien membantu menghindari duplikasi dan memastikan konsistensi di seluruh modul.
Setiap modul memiliki bagian manajemen skemanya sendiri, tempat Anda dapat mendefinisikan dan memelihara struktur data terkait bisnis. Skema ini dapat digunakan kembali dalam modul atau direferensikan oleh modul lain.
Misalnya, modul Layanan Pengguna mendefinisikan skema terkait pengguna. Modul Layanan Pesanan mendefinisikan skema terkait pesanan. Jika Layanan Pesanan perlu mereferensikan info pengguna, ia dapat dengan mudah menggunakan kembali skema Layanan Pengguna—tidak perlu membuatnya ulang.
Dari Postman ke Apidog: Mengatur Koleksi & Titik Akhir yang Diimpor
Jika tim Anda sebelumnya menggunakan Postman, Anda dapat dengan mudah memigrasi koleksi dan titik akhir yang ada ke Apidog.
Selama impor:
- Setiap Koleksi Postman menjadi Modul.
- Struktur folder dipetakan secara otomatis.
- Titik akhir dan skema dipertahankan.
Ini memungkinkan Anda mempertahankan struktur API yang sudah Anda kenal sambil memanfaatkan sistem modular Apidog.
Kesimpulan
Dengan mendefinisikan modul yang jelas, mengorganisir folder, dan menggunakan kembali skema, Anda dapat menjaga proyek Apidog Anda tetap rapi, skalabel, dan mudah untuk berkolaborasi.
Desain modular Apidog membantu tim bekerja lebih cepat, menghindari kebingungan, dan mengelola API yang kompleks dengan lebih efisien — mulai dari desain hingga dokumentasi hingga pengujian.