Read (List Data)

Endpoint /read adalah endpoint universal untuk mengambil data dari database. Endpoint ini mendukung dua mode operasi (paginasi dan non-paginasi), pencarian teks, pengurutan multi-kolom, filter WHERE kompleks, dan pemilihan kolom selektif.

Kapan Menggunakan /read (When to Use /read)

Dua Mode Operasi (Two Operation Modes)

Mode operasi ditentukan secara otomatis berdasarkan keberadaan parameter page di request body:

Mode Paginasi (Pagination Mode)

Kirim parameter page dan per_page untuk mendapatkan data per halaman:

{
    "page": 1,
    "per_page": 10
}

Response menyertakan blok pagination yang berisi informasi navigasi halaman:

{
    "success": true,
    "data": [
        { "supplier_id": "...", "supplier_code": "SUP-001", "supplier_name": "PT Maju Jaya" },
        { "supplier_id": "...", "supplier_code": "SUP-002", "supplier_name": "CV Sejahtera" }
    ],
    "count": 2,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_records": 42,
        "total_pages": 5,
        "has_next": true,
        "has_previous": false
    }
}

Untuk berpindah halaman, cukup ubah nilai page:

{ "page": 2, "per_page": 10 }

Mode Non-Paginasi (Non-Pagination Mode)

Jika page tidak dikirim, seluruh data yang cocok dikembalikan dalam satu response. Parameter limit membatasi jumlah record yang dikembalikan (default 1000, maksimal 5000):

{
    "limit": 100,
    "select": ["supplier_id", "supplier_code", "supplier_name"]
}

{
    "success": true,
    "data": [
        { "supplier_id": "...", "supplier_code": "SUP-001", "supplier_name": "PT Maju Jaya" },
        { "supplier_id": "...", "supplier_code": "SUP-002", "supplier_name": "CV Sejahtera" }
    ],
    "count": 2
}

Blok pagination tidak disertakan di mode non-paginasi.

Pencarian Teks (Text Search)

Parameter search_value mencari data menggunakan operator LIKE. Secara default, pencarian dilakukan di kolom pertama yang terdaftar di payload. Kolom target dapat diubah menggunakan search_by:

{
    "page": 1,
    "per_page": 10,
    "search_value": "Jakarta",
    "search_by": "city"
}

Filter WHERE (WHERE Filtering)

Parameter where mendukung dua format untuk memfilter data.

Format Sederhana (Simple Format)

Semua kondisi digabungkan dengan AND, operator default =:

{
    "page": 1,
    "per_page": 20,
    "where": [
        { "key": "is_active", "value": true },
        { "key": "city", "value": "Jakarta" }
    ]
}

Format Kompleks (Complex Format)

Mendukung operator lengkap dan logika AND/OR:

{
    "page": 1,
    "per_page": 20,
    "where": {
        "logic": "AND",
        "conditions": [
            { "key": "city", "operator": "=", "value": "Jakarta" },
            { "key": "is_active", "operator": "=", "value": true },
            { "key": "credit_limit", "operator": ">=", "value": 50000000 }
        ]
    }
}

Operator yang Didukung (Supported Operators)

Pengurutan (Sorting)

Parameter sort_columns mengatur urutan data. Mendukung pengurutan multi-kolom:

{
    "page": 1,
    "per_page": 20,
    "sort_columns": [
        { "column": "city", "direction": "ASC" },
        { "column": "supplier_name", "direction": "ASC" }
    ]
}

Jika sort_columns tidak dikirim, data diurutkan berdasarkan primary key secara ascending.

Pemilihan Kolom (Column Selection)

Parameter select membatasi kolom yang dikembalikan. Berguna untuk mengurangi ukuran response jika hanya membutuhkan beberapa kolom:

{
    "page": 1,
    "per_page": 50,
    "select": ["supplier_id", "supplier_code", "supplier_name", "is_active"]
}

Kolom yang tidak terdaftar di fieldName payload akan ditolak dengan error 400.

Sumber Data (Data Source)

Endpoint /read menentukan sumber data berdasarkan prioritas resolusi:

viewName → viewQuery → tableName

Contoh konfigurasi viewQuery untuk menampilkan data supplier beserta nama negara dari tabel referensi:

{
    "tableName": "supplier",
    "viewQuery": "SELECT s.*, c.country_name FROM supplier s LEFT JOIN country c ON c.country_id = s.country_id"
}

Dengan konfigurasi ini, endpoint /read mengembalikan data yang sudah di-JOIN dengan tabel country.

Perbandingan /read vs /datatables (Comparison)

Langkah Selanjutnya (Next Steps)

• First — Detail Data untuk mengambil satu record berdasarkan primary key
• CRUD Dasar untuk operasi create, update, dan delete
• POST /read untuk spesifikasi teknis lengkap (parameter, error code, cache)