Pola Action-Based
Konsep endpoint berbasis action menggunakan HTTP POST untuk semua operasi
RESTForge menggunakan pola action-based sebagai pengganti pendekatan REST tradisional. Seluruh operasi dilakukan melalui HTTP POST dengan nama action di URL path, bukan melalui perbedaan HTTP method seperti GET, PUT, atau DELETE.
Ikhtisar (Overview)
Dalam pola action-based, setiap operasi terhadap sebuah endpoint diwakili oleh nama action yang eksplisit di segmen terakhir URL:
POST /api/{project}/{endpoint}/{action}Contoh: untuk melakukan operasi create pada endpoint supplier di project mini-inventory, request dikirim ke:
POST /api/mini-inventory/supplier/createPola ini berlaku konsisten untuk seluruh operasi, baik CRUD standar maupun operasi lanjutan seperti export, import, atau aggregate.
Perbandingan dengan REST Tradisional (Comparison with Traditional REST)
REST tradisional menggunakan kombinasi HTTP method dan resource URL untuk membedakan operasi. RESTForge memilih pendekatan berbeda di mana method selalu POST dan operasi ditentukan oleh nama action.
| Operasi | REST Tradisional | RESTForge (Action-Based) |
|---|---|---|
| Membuat data | POST /api/suppliers | POST /api/mini-inventory/supplier/create |
| Membaca satu record | GET /api/suppliers/:id | POST /api/mini-inventory/supplier/first |
| Membaca banyak record | GET /api/suppliers | POST /api/mini-inventory/supplier/read |
| Mengubah data | PUT /api/suppliers/:id | POST /api/mini-inventory/supplier/update |
| Menghapus data | DELETE /api/suppliers/:id | POST /api/mini-inventory/supplier/delete |
RESTForge tidak sepenuhnya REST purist, tetapi pragmatis. Trade-off ini diambil dengan sadar karena kebutuhan praktis tim backend lebih penting daripada konformitas penuh terhadap standar REST.
Mengapa Pendekatan Ini Dipilih (Why This Approach Was Chosen)
| Manfaat | Penjelasan |
|---|---|
| Mendukung query kompleks | Filter dengan nested condition, multi-operator, dan logika AND/OR dapat dikirim di body tanpa limitasi URL length |
| Konsisten lintas operasi | Tim tidak perlu beralih antara GET, POST, PUT, DELETE dengan semantik yang berbeda-beda |
| Mendukung payload besar | Operasi seperti import, bulk create, atau composite master-detail dapat dikirim dalam satu request |
| Mudah didokumentasikan | Setiap action adalah resource terpisah dengan format yang sama sehingga lebih mudah di-document dan di-version |
Pada pendekatan REST tradisional, operasi baca yang membutuhkan filter kompleks sering kali menghadapi kendala panjang URL. Dengan action-based pattern, seluruh parameter dikirim di request body sehingga tidak ada batasan tersebut.
Tujuh Action Standar (Seven Standard Actions)
Setiap endpoint yang di-generate oleh RESTForge memiliki hingga tujuh action standar yang dapat diaktifkan melalui konfigurasi payload:
| Action | Method | Fungsi | Use Case |
|---|---|---|---|
datatables | POST | Data dengan pagination, search, dan sort | Tabel data di browser (DataTables.net) |
create | POST | Insert satu record baru | Form tambah data |
update | POST | Update satu record berdasarkan primary key | Form edit data |
delete | POST | Hapus satu record berdasarkan primary key | Tombol hapus |
first | POST | Membaca satu record berdasarkan kondisi | Halaman detail atau form edit |
lookup | GET / POST | Data untuk dropdown atau autocomplete | Komponen select/combobox |
read | POST | Membaca banyak record dengan pagination dan filter | API konsumsi, mobile app, reporting |
Contoh URL untuk project mini-inventory dengan endpoint supplier:
POST http://localhost:3000/api/mini-inventory/supplier/datatables
POST http://localhost:3000/api/mini-inventory/supplier/create
POST http://localhost:3000/api/mini-inventory/supplier/update
POST http://localhost:3000/api/mini-inventory/supplier/delete
POST http://localhost:3000/api/mini-inventory/supplier/first
GET http://localhost:3000/api/mini-inventory/supplier/lookup?search=keyword
POST http://localhost:3000/api/mini-inventory/supplier/lookup
POST http://localhost:3000/api/mini-inventory/supplier/readAction Lanjutan (Advanced Actions)
Selain tujuh action standar, RESTForge menyediakan action lanjutan untuk kebutuhan yang lebih spesifik:
| Kategori | Action | Fungsi |
|---|---|---|
| Pengambilan data lanjutan | aggregate | Fungsi agregasi (COUNT, SUM, AVG, MIN, MAX, GROUP BY) |
| Operasi khusus | adjust | Atomic increment/decrement field numerik |
| Workflow | change-status | Perubahan status record dengan validasi transisi dan hook |
| CRUD Composite | create-composite | Buat header + detail items dalam satu transaksi |
read-composite | Baca header beserta detail items | |
update-composite | Update header + insert/update/delete detail items | |
| Export dan Import | export | Trigger async export ke Excel |
import-upload | Upload file Excel untuk import | |
import-preview | Validasi dan preview data import | |
import-commit | Eksekusi INSERT/UPDATE ke database | |
| Resource Lock | lock/acquire | Mengunci record untuk mencegah concurrent edit |
lock/release | Melepas kunci record | |
lock/status | Mengecek status kunci record |
Action lanjutan memerlukan konfigurasi tambahan di file payload. Misalnya, aggregate membutuhkan aggregateConfig, sedangkan create-composite membutuhkan masterDetail. Detail konfigurasi tersedia di halaman dokumentasi masing-masing fitur.
Langkah Selanjutnya (Next Steps)
- Struktur Payload untuk memahami file konfigurasi yang mendefinisikan action mana saja yang diaktifkan
- Pola URL untuk katalog lengkap URL dan pemetaan action ke konfigurasi payload