Struktur Payload

Payload adalah file JSON yang berfungsi sebagai blueprint untuk API generation. Satu file payload mendefinisikan satu endpoint API untuk satu tabel database, termasuk kolom yang di-expose, query yang digunakan, dan action yang tersedia.

Ikhtisar (Overview)

Pipeline kerja RESTForge dimulai dari payload:

┌──────────────┐      ┌───────────────┐      ┌──────────────────┐
│  Payload JSON │─────▶│  Generator    │─────▶│  JavaScript Code │
│  (konfigurasi)│      │  (CLI)        │      │  (siap jalankan) │
└──────────────┘      └───────────────┘      └──────────────────┘

Payload JSON berfungsi sebagai single source of truth. Generator membaca payload dan menghasilkan module JavaScript yang optimal per database. Module inilah yang dijalankan oleh Express server saat runtime.

Contoh Payload Dasar (Basic Payload Example)

{
    "tableName": "supplier",
    "primaryKey": "supplier_id",
    "fieldName": [
        "supplier_id",
        "supplier_code",
        "supplier_name",
        "contact_person",
        "phone",
        "email",
        "is_active"
    ],
    "datatablesQuery": "file:query/supplier-datatables.sql",
    "datatablesWhere": [
        "supplier_code",
        "supplier_name",
        "contact_person",
        "all"
    ],
    "action": {
        "datatables": true,
        "create": true,
        "update": true,
        "delete": true,
        "first": true,
        "lookup": true,
        "read": true
    }
}

Payload di atas menghasilkan tujuh endpoint API untuk tabel supplier dengan kemampuan pencarian di kolom supplier_code, supplier_name, dan contact_person.

Properti Inti (Core Properties)

tableName

Nama tabel di database. Jika tabel berada di schema selain public, gunakan format "schema.table_name".

"tableName": "supplier"              // schema default (public)
"tableName": "inventory.supplier"    // schema eksplisit

primaryKey

Nama kolom primary key. Jika tidak disebutkan, generator menggunakan fieldName[0] sebagai fallback.

"primaryKey": "supplier_id"

fieldName

Array berisi nama kolom yang akan di-handle oleh API. Urutan yang direkomendasikan:

1. Primary key
2. Code/number (unique identifier)
3. Name/title
4. Descriptive fields
5. Status fields (is_active, status)
6. Audit fields (created_at, created_by, updated_at, updated_by)

"fieldName": [
    "supplier_id",       // 1. Primary key
    "supplier_code",     // 2. Code
    "supplier_name",     // 3. Name
    "contact_person",    // 4. Descriptive
    "phone",             // 4. Descriptive
    "email",             // 4. Descriptive
    "is_active",         // 5. Status
    "created_at",        // 6. Audit
    "created_by"         // 6. Audit
]

datatablesQuery

Query SQL untuk endpoint datatables. Mendukung dua format:

Inline query:

"datatablesQuery": "SELECT supplier_id, supplier_code, supplier_name FROM supplier"

External file (direkomendasikan untuk query panjang atau query dengan JOIN):

"datatablesQuery": "file:query/supplier-datatables.sql"

File SQL disimpan di folder payload/query/ relatif terhadap folder payload/. Query tidak boleh mengandung WHERE, ORDER BY, atau LIMIT karena ketiga clause tersebut ditambahkan secara otomatis oleh generator.

datatablesWhere

Array kolom yang dapat di-search di endpoint datatables. Tambahkan "all" untuk mengaktifkan pencarian di seluruh kolom yang terdaftar.

"datatablesWhere": ["supplier_code", "supplier_name", "contact_person", "all"]

Hindari kolom berikut untuk search: primary key (UUID), foreign key, timestamp, dan kolom dengan tipe data TEXT yang terlalu panjang.

action

Definisi action yang akan di-generate. Set true untuk action yang dibutuhkan dan false atau hilangkan untuk yang tidak.

Tipe Query Deklaratif (Declarative Query Types)

Selain datatablesQuery, payload mendukung tipe query tambahan untuk endpoint yang berbeda:

Prioritas Resolusi (Resolution Priority)

Setiap endpoint memiliki urutan prioritas dalam memilih sumber data:

/datatables  → datatablesQuery → fallback: SELECT * FROM tableName
/read        → viewName → viewQuery → tableName
/first       → viewName → viewQuery → tableName
/lookup      → viewName → tableName
/export      → exportQuery → fallback: SELECT fieldName FROM tableName

Contoh penggunaan viewQuery untuk endpoint /read dan /first yang memerlukan JOIN:

{
    "tableName": "supplier",
    "primaryKey": "supplier_id",
    "viewQuery": "SELECT s.supplier_id, s.supplier_code, s.supplier_name, c.country_name FROM supplier s LEFT JOIN country c ON c.country_id = s.country_id",
    "datatablesQuery": "SELECT supplier_id, supplier_code, supplier_name FROM supplier"
}

Dengan konfigurasi ini, endpoint /datatables menggunakan query sederhana yang cepat, sedangkan /read dan /first menggunakan query dengan JOIN yang menampilkan data lebih lengkap.

Format File Reference

Untuk query panjang, simpan di file terpisah:

{
    "datatablesQuery": "file:query/supplier_list.sql",
    "viewQuery": "file:query/supplier_detail.sql",
    "exportQuery": "file:query/supplier_export.sql"
}

File SQL disimpan di folder payload/query/ relatif terhadap lokasi payload JSON.

Properti Opsional Lanjutan (Optional Advanced Properties)

Selain properti inti, payload mendukung properti lanjutan untuk fitur yang lebih spesifik:

Praktik Terbaik (Best Practices)

Penamaan file payload: Gunakan nama yang sama dengan endpoint. File supplier.json menghasilkan endpoint supplier, file stock_inbound.json menghasilkan endpoint stock_inbound.

Urutan field: Ikuti konvensi urutan (PK, code, name, descriptive, status, audit) agar konsisten di seluruh project.

Pemilihan search column: Pilih kolom yang sering di-search oleh pengguna dan bertipe teks. Hindari UUID, timestamp, atau kolom TEXT yang terlalu panjang.

Primary key eksplisit: Selalu sertakan primaryKey meskipun primary key bernama id, agar generator tidak bergantung pada fallback.

External SQL file: Gunakan file SQL terpisah untuk query yang mengandung JOIN atau lebih dari satu baris. Hal ini memudahkan maintenance dan review.

Langkah Selanjutnya (Next Steps)

• Membuat Payload untuk tutorial langkah demi langkah membuat payload pertama
• Pola URL untuk memahami bagaimana action di payload dipetakan ke URL endpoint