Membuat Payload

Payload adalah file JSON yang mendefinisikan struktur API untuk setiap tabel database. RESTForge menggunakan payload ini untuk men-generate model, module, dan route secara otomatis.

Struktur Dasar Payload (Basic Payload Structure)

{
    "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
    }
}

Penjelasan Property (Property Reference)

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)

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 endpoint yang akan di-generate. Set true untuk endpoint yang dibutuhkan dan false untuk yang tidak.

Action lanjutan seperti export, import, adjust, aggregate, createComposite, updateComposite, dan readComposite tersedia tetapi memerlukan konfigurasi tambahan di payload.

Query dengan JOIN (Queries with JOIN)

Untuk endpoint yang menampilkan data dari beberapa tabel, gunakan file SQL terpisah:

SELECT a.item_product_id,
       a.product_code,
       a.product_name,
       b.category_name,
       a.selling_price,
       a.stock,
       a.is_active
FROM item_product a
INNER JOIN category b ON b.category_id = a.category_id

Gunakan alias tabel (a, b, dst.) untuk menghindari ambiguous column names.

Property Opsional Tambahan (Additional Optional Properties)

Selain property dasar di atas, payload mendukung property lanjutan:

Detail setiap property lanjutan tersedia di halaman dokumentasi masing-masing di bagian Panduan Fitur.

Validasi Payload (Payload Validation)

Sebelum menjalankan generator, pastikan payload valid:

1. Format JSON valid (tidak ada trailing comma, tanda kutip matching)
2. tableName sesuai dengan nama tabel di database
3. fieldName berisi semua kolom yang diperlukan
4. datatablesQuery meng-SELECT semua kolom yang ada di fieldName
5. datatablesWhere berisi kolom yang relevan untuk pencarian

Validasi format JSON dapat dilakukan melalui JSON validator online atau melalui VS Code yang secara otomatis menandai syntax error.