RESTForge

POST /first

Spesifikasi endpoint first untuk mengambil satu record

Endpoint /first digunakan untuk mengambil satu record berdasarkan kondisi kesamaan (equality) sederhana. Endpoint ini selalu mengambil data langsung dari database tanpa cache.

Referensi Cepat (Quick Reference)

PropertiNilai
MethodPOST
URL/api/{project}/{endpoint}/first
Content-Typeapplication/json
Status Sukses200 OK
DatabasePostgreSQL, MySQL, Oracle
Hasil Maksimum1 record (LIMIT 1)
CacheTidak ada (selalu fresh dari database)
Default ScopeTidak diterapkan

Ikhtisar (Overview)

Endpoint /first dirancang untuk mengambil detail satu record berdasarkan kondisi WHERE sederhana. Parameter where bersifat wajib dan hanya mendukung operator kesamaan (=). Hasil query dibatasi maksimum 1 record (LIMIT 1).

Endpoint ini tidak menggunakan cache Redis dan tidak menerapkan default scope. Setiap request selalu mengambil data terbaru langsung dari database. Kondisi WHERE hanya mendukung operator kesamaan (=), tidak mendukung operator kompleks seperti LIKE, BETWEEN, atau IN.

Format Request (Request Format)

Parameter (Parameters)

ParameterTipeWajibKeterangan
whereobject atau arrayYaKondisi filter dengan operator = saja
selectarrayTidakKolom spesifik yang akan dikembalikan

Format WHERE

Parameter where mendukung dua format penulisan:

Format object (satu kondisi):

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

Format array (beberapa kondisi, implicit AND):

{
    "where": [
        { "key": "supplier_code", "value": "SUP-001" },
        { "key": "is_active", "value": true }
    ]
}

Setiap elemen kondisi terdiri dari key (nama kolom) dan value (nilai yang dicari). Semua kondisi menggunakan operator = secara implisit.

Contoh Request (Request Examples)

Mengambil record berdasarkan primary key:

POST /api/mini-inventory/supplier/first
{
    "where": {
        "key": "supplier_id",
        "value": "550e8400-e29b-41d4-a716-446655440000"
    }
}

Mengambil record berdasarkan field non-primary key:

POST /api/mini-inventory/supplier/first
{
    "where": {
        "key": "supplier_code",
        "value": "SUP-001"
    }
}

Mengambil record dengan beberapa kondisi:

POST /api/mini-inventory/supplier/first
{
    "where": [
        { "key": "city", "value": "Jakarta" },
        { "key": "is_active", "value": true }
    ]
}

Mengambil record dengan seleksi kolom:

POST /api/mini-inventory/supplier/first
{
    "where": {
        "key": "supplier_id",
        "value": "550e8400-e29b-41d4-a716-446655440000"
    },
    "select": ["supplier_id", "supplier_code", "supplier_name", "email"]
}

Format Response (Response Format)

Response Sukses dengan Data (Success with Data)

HTTP 200 OK

{
    "success": true,
    "data": {
        "supplier_id": "550e8400-e29b-41d4-a716-446655440000",
        "supplier_code": "SUP-001",
        "supplier_name": "PT Maju Jaya",
        "email": "contact@majujaya.com",
        "phone": "021-5551234",
        "city": "Jakarta",
        "is_active": true,
        "created_at": "2026-04-16T10:30:00.000Z",
        "created_by": "Input from API",
        "updated_at": "2026-04-16T10:30:00.000Z",
        "updated_by": null
    },
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Response Sukses tanpa Data (Success Empty)

Jika tidak ada record yang cocok dengan kondisi WHERE, response tetap 200 OK dengan data bernilai null:

HTTP 200 OK

{
    "success": true,
    "data": null,
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Response Error (Error Responses)

400 — Payload kosong:

{
    "success": false,
    "error": "Invalid payload",
    "message": "Payload cannot be empty",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

400 — Parameter WHERE tidak dikirim:

{
    "success": false,
    "error": "Invalid payload",
    "message": "WHERE parameter is required",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

400 — Format WHERE tidak valid:

{
    "success": false,
    "error": "Invalid payload",
    "message": "Invalid WHERE format. Expected object {key, value} or array of {key, value}",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

400 — Field tidak valid:

{
    "success": false,
    "error": "Invalid field",
    "message": "Field 'unknown_field' is not a valid column",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

500 — Internal server error:

{
    "success": false,
    "error": "Internal server error",
    "message": "An unexpected error occurred",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Resolusi Sumber Data (Data Source Resolution)

Endpoint /first menggunakan prioritas resolusi sumber data berikut:

PrioritasSumberKonfigurasi Payload
1 (tertinggi)Database VIEW"viewName": "vw_supplier_detail"
2Virtual view"viewQuery": "SELECT ... JOIN ..."
3 (fallback)Tabel langsung"tableName": "supplier"

Sistem memeriksa konfigurasi payload secara berurutan. Jika viewName dikonfigurasi, query akan dijalankan terhadap database VIEW tersebut. Jika tidak ada viewName tetapi ada viewQuery, query virtual view yang akan digunakan. Jika keduanya tidak ada, query dijalankan langsung terhadap tabel yang didefinisikan di tableName.

Perbandingan dengan /read (Comparison with /read)

Aspek/first/read
TujuanMengambil satu record spesifikMengambil daftar record
Hasil maksimum1 recordMultiple record (paginasi atau limit)
Operator WHEREHanya = (equality)Operator kompleks (=, !=, >, <, LIKE, BETWEEN, IN, dll.)
Logika WHEREImplicit ANDAND/OR eksplisit
PaginasiTidakYa (mode paginasi)
CacheTidak adaRedis cache
Default scopeTidak diterapkanDiterapkan jika dikonfigurasi
Use caseDetail record, form edit, validasi dataList data, reporting, search

Langkah Selanjutnya (Next Steps)

On this page

Referensi Cepat (Quick Reference)Ikhtisar (Overview)Format Request (Request Format)Parameter (Parameters)Format WHEREContoh Request (Request Examples)Format Response (Response Format)Response Sukses dengan Data (Success with Data)Response Sukses tanpa Data (Success Empty)Response Error (Error Responses)Resolusi Sumber Data (Data Source Resolution)Perbandingan dengan /read (Comparison with /read)Langkah Selanjutnya (Next Steps)