First (Detail Data)

Endpoint /first dirancang untuk mengambil satu record dari database berdasarkan primary key. Endpoint ini digunakan untuk keperluan halaman detail dan form edit di sisi frontend, di mana aplikasi perlu menampilkan data lengkap satu entitas.

Kapan Menggunakan /first (When to Use /first)

Skenario	Contoh
Menampilkan halaman detail	Klik baris supplier di tabel → buka halaman detail supplier
Mengisi form edit	Membuka form edit supplier yang sudah ada
Verifikasi setelah create/update	Memastikan data yang baru disimpan sudah benar
Mengambil data referensi tunggal	Mengambil satu record konfigurasi berdasarkan kode

Cara Kerja (How It Works)

Endpoint /first menerima parameter where berisi pasangan key-value yang menentukan record mana yang diambil. Hanya operator = (equality) yang didukung, dan hasilnya selalu maksimal satu record.

POST /api/mini-inventory/supplier/first

{
    "where": { "key": "supplier_id", "value": "550e8400-e29b-41d4-a716-446655440000" }
}

Response:

{
    "success": true,
    "count": 1,
    "data": [
        {
            "supplier_id": "550e8400-e29b-41d4-a716-446655440000",
            "supplier_code": "SUP-001",
            "supplier_name": "PT Maju Jaya",
            "contact_person": "John Doe",
            "phone": "021-5551234",
            "email": "contact@majujaya.com",
            "is_active": true,
            "created_at": "2026-04-16T10:30:00.000Z",
            "created_by": "Input from API"
        }
    ],
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Jika record tidak ditemukan, response tetap sukses (200 OK) dengan count: 0 dan array data kosong:

{
    "success": true,
    "count": 0,
    "data": [],
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Data tidak ditemukan bukan error. Endpoint /first mengembalikan HTTP 200 meskipun tidak ada record yang cocok. Hal ini berbeda dengan endpoint /update atau /delete yang mengembalikan 404 jika record tidak ditemukan.

Format WHERE

Parameter where bersifat wajib dan mendukung dua format:

Format object (direkomendasikan):

{
    "where": { "key": "supplier_id", "value": "550e8400-..." }
}

Format array (kompatibilitas mundur, maksimal 1 elemen):

{
    "where": [{ "key": "supplier_id", "value": "550e8400-..." }]
}

Batasan WHERE (WHERE Restrictions)

Endpoint /first memiliki batasan yang berbeda dari /read:

Hanya menerima satu kondisi WHERE
Hanya mendukung operator = (equality, implisit)
Tidak mendukung format kompleks (conditions, logic, operator LIKE/BETWEEN/IN)
Array where dengan lebih dari satu elemen akan ditolak

Untuk query yang lebih kompleks, gunakan endpoint /read.

Memilih Kolom Tertentu (Selecting Specific Columns)

Parameter select membatasi kolom yang dikembalikan. Berguna untuk mengurangi ukuran response atau hanya mengambil field yang dibutuhkan oleh frontend:

POST /api/mini-inventory/supplier/first

{
    "where": { "key": "supplier_id", "value": "550e8400-..." },
    "select": ["supplier_id", "supplier_code", "supplier_name", "email"]
}

Response hanya berisi kolom yang diminta:

{
    "success": true,
    "count": 1,
    "data": [
        {
            "supplier_id": "550e8400-...",
            "supplier_code": "SUP-001",
            "supplier_name": "PT Maju Jaya",
            "email": "contact@majujaya.com"
        }
    ],
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Menampilkan Data dengan JOIN (Displaying JOINed Data)

Secara default, endpoint /first hanya mengambil data dari satu tabel. Untuk menampilkan data lengkap yang memerlukan JOIN (misalnya nama kategori dari tabel referensi), konfigurasi viewQuery atau viewName di payload:

payload/item-product.json (contoh viewQuery)

{
    "tableName": "item_product",
    "primaryKey": "item_product_id",
    "viewQuery": "SELECT a.*, b.category_name FROM item_product a LEFT JOIN category b ON b.category_id = a.category_id"
}

Dengan konfigurasi ini, endpoint /first untuk item-product mengembalikan field category_name yang berasal dari tabel category.

Prioritas Sumber Data (Data Source Priority)

viewName → viewQuery → tableName

Prioritas	Konfigurasi	Keterangan
1	`viewName`	Database VIEW yang sudah dibuat
2	`viewQuery`	Virtual view (SQL dengan JOIN), tanpa perlu membuat VIEW di database
3	`tableName`	Langsung query ke tabel

Endpoint /first dan /read menggunakan prioritas resolusi sumber data yang identik. Jika viewQuery dikonfigurasi untuk endpoint /read, data yang sama juga tersedia di endpoint /first.

Karakteristik Penting (Key Characteristics)

Aspek	Perilaku
Cache	Tidak di-cache. Selalu query langsung ke database untuk mendapatkan data terkini
Default scope	Tidak diterapkan. Seluruh data (termasuk yang tidak aktif) dapat diambil
Hasil maksimal	1 record (LIMIT 1 diterapkan secara otomatis)

Perbandingan /first vs /read (Comparison)

Aspek	`/first`	`/read`
Jumlah record	Maksimal 1	Banyak (dengan pagination atau limit)
WHERE	Satu kondisi, operator `=` saja	Banyak kondisi, operator lengkap
Cache	Tidak di-cache	Di-cache di Redis
Default scope	Tidak diterapkan	Diterapkan
Use case	Halaman detail, form edit	Daftar data, tabel, reporting

Langkah Selanjutnya (Next Steps)

CRUD Dasar untuk operasi create, update, dan delete
Read — List Data untuk mengambil daftar data dengan filter
POST /first untuk spesifikasi teknis lengkap (semua parameter, format error, resolusi sumber data)

First (Detail Data)

On this page