Format Response

RESTForge menggunakan response envelope yang konsisten di seluruh endpoint. Setiap response mengikuti struktur standar sehingga client dapat memproses hasil dari action manapun dengan pola yang sama.

Envelope Standar (Standard Envelope)

Struktur dasar response untuk operasi yang berhasil:

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

Field	Tipe	Keterangan
`success`	boolean	`true` jika operasi berhasil, `false` jika gagal
`message`	string	Pesan deskriptif tentang hasil operasi
`data`	object/array	Data hasil operasi (object untuk single record, array untuk multiple)
`timestamp`	string	Waktu eksekusi operasi dalam format ISO 8601

Response Sukses (Success Response)

Operasi Mutasi (Mutation Operations)

Create mengembalikan record yang baru dibuat beserta field yang di-auto-generate (seperti UUID dan timestamp):

{
    "success": true,
    "message": "supplier data successfully added",
    "data": {
        "supplier_id": "550e8400-e29b-41d4-a716-446655440000",
        "supplier_code": "SUP-001",
        "supplier_name": "PT Maju Jaya",
        "email": "contact@majujaya.com",
        "is_active": true,
        "created_at": "2026-04-16T10:30:00.000Z",
        "created_by": "USER001"
    },
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Update mengembalikan record setelah perubahan diterapkan:

{
    "success": true,
    "message": "supplier data successfully updated",
    "data": {
        "supplier_id": "550e8400-e29b-41d4-a716-446655440000",
        "supplier_name": "PT Maju Jaya Sejahtera",
        "updated_at": "2026-04-16T11:00:00.000Z",
        "updated_by": "USER001"
    },
    "timestamp": "2026-04-16T11:00:00.000Z"
}

Delete mengembalikan konfirmasi penghapusan:

{
    "success": true,
    "message": "supplier data successfully deleted",
    "timestamp": "2026-04-16T11:30:00.000Z"
}

Operasi Baca (Read Operations)

First mengembalikan satu record berdasarkan kondisi:

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

Read (mode non-paginasi) mengembalikan array data:

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

Response Khusus DataTables (DataTables Response Format)

Endpoint /datatables menggunakan format response native jQuery DataTables.net untuk kompatibilitas (compatibility) langsung dengan library frontend:

{
    "draw": 1,
    "recordsTotal": 150,
    "recordsFiltered": 45,
    "data": [
        {
            "supplier_id": "550e8400-...",
            "supplier_code": "SUP-001",
            "supplier_name": "PT Maju Jaya",
            "city": "Jakarta",
            "is_active": true
        }
    ]
}

Field	Tipe	Keterangan
`draw`	number	Counter request dari client (untuk sinkronisasi)
`recordsTotal`	number	Total record di database (sebelum filter)
`recordsFiltered`	number	Total record setelah filter search diterapkan
`data`	array	Array record untuk halaman saat ini

Response datatables adalah satu-satunya format yang tidak menggunakan envelope standar {success, data, message}. Hal ini disengaja agar kompatibel langsung dengan DataTables.net tanpa perlu transformasi di sisi client.

Response Lookup

Endpoint /lookup mengembalikan data dalam format {id, text} yang siap digunakan oleh komponen dropdown atau autocomplete:

{
    "success": true,
    "count": 3,
    "data": [
        { "id": "550e8400-...", "text": "SUP-001 - PT Maju Jaya" },
        { "id": "661f9511-...", "text": "SUP-002 - CV Sejahtera" },
        { "id": "772a0622-...", "text": "SUP-003 - PT Global Teknologi" }
    ],
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Response Paginasi (Pagination Response)

Endpoint /read (POST) dengan parameter pagination mengembalikan metadata halaman:

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

Field	Tipe	Keterangan
`current_page`	number	Halaman saat ini
`per_page`	number	Jumlah record per halaman
`total_records`	number	Total record yang cocok dengan filter
`total_pages`	number	Total halaman yang tersedia
`has_next`	boolean	Apakah ada halaman selanjutnya
`has_previous`	boolean	Apakah ada halaman sebelumnya

Response Error (Error Response)

Error Umum (General Error)

{
    "success": false,
    "error": "Record not found",
    "message": "supplier not found",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Error Validasi (Validation Error)

Jika validasi input gagal, server mengembalikan HTTP 400 dengan detail error per field:

{
    "success": false,
    "error": "Validation failed",
    "message": "Invalid data",
    "errors": {
        "supplier_code": ["Field supplier_code is required"],
        "email": ["Field email must be a valid email address"]
    },
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Field errors berisi object di mana key adalah nama field dan value adalah array pesan error. Satu field dapat memiliki lebih dari satu pesan error jika melanggar beberapa constraint sekaligus.

Error Lainnya (Other Common Errors)

Duplicate key (409):

{
    "success": false,
    "error": "Duplicate entry",
    "message": "Supplier code already exists",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Foreign key constraint (409 pada delete, 400 pada create/update):

{
    "success": false,
    "error": "Foreign key constraint",
    "message": "Cannot delete supplier — record is still referenced by other tables",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Guard clause (409):

{
    "success": false,
    "error": "Constraint violation",
    "message": "Adjustment would result in negative stock",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Kode Status HTTP (HTTP Status Codes)

Kode	Keterangan	Kapan Digunakan
200	OK	Operasi berhasil selain pembuatan data baru (read, update, delete, adjust, datatables, lookup, aggregate)
201	Created	Record baru berhasil dibuat (hanya `/create` dan `/create-composite`)
400	Bad Request	Payload kosong, field wajib hilang, validasi gagal, format WHERE salah, FK constraint pada create/update
401	Unauthorized	Autentikasi diperlukan (jika auth middleware aktif)
404	Not Found	Record tidak ditemukan pada operasi update, delete, atau adjust. Endpoint `/read` dan `/first` dengan data kosong tetap mengembalikan 200
409	Conflict	Duplicate key (unique constraint), FK constraint pada delete (record masih direferensikan), guard clause pada adjust
429	Too Many Requests	Rate limit terlampaui
500	Internal Server Error	Error tidak terduga di server (database error, lock failure, runtime error)

Langkah Selanjutnya (Next Steps)

Body Options untuk memahami cara mengirim opsi tambahan bersama data request
Pola URL untuk katalog lengkap action yang tersedia

Format Response

On this page