RESTForge

Pola URL

Format URL universal RESTForge: POST /api/{project}/{endpoint}/{action}

Seluruh endpoint RESTForge mengikuti satu pola URL universal. Konsistensi (consistency) ini menyederhanakan dokumentasi, monitoring, dan integrasi tooling karena setiap endpoint memiliki format yang dapat diprediksi.

Format URL Universal (Universal URL Format)

{METHOD} /api/{project}/{endpoint}/{action}

Setiap segmen URL memiliki peran spesifik:

SegmenKeteranganContoh
/apiPrefix tetap untuk semua endpoint RESTForge/api
{project}Nama project, ditentukan saat menjalankan server via --projectmini-inventory
{endpoint}Nama endpoint, berasal dari nama file payloadsupplier
{action}Nama operasi yang akan dijalankancreate, datatables, first

Contoh URL (URL Examples)

Dengan asumsi server berjalan di http://localhost:3000 untuk project mini-inventory:

POST http://localhost:3000/api/mini-inventory/supplier/datatables
POST http://localhost:3000/api/mini-inventory/supplier/create
POST http://localhost:3000/api/mini-inventory/supplier/update
POST http://localhost:3000/api/mini-inventory/supplier/delete
POST http://localhost:3000/api/mini-inventory/supplier/first
GET  http://localhost:3000/api/mini-inventory/supplier/lookup?search=keyword
POST http://localhost:3000/api/mini-inventory/supplier/lookup
POST http://localhost:3000/api/mini-inventory/supplier/read
POST http://localhost:3000/api/mini-inventory/supplier/aggregate
POST http://localhost:3000/api/mini-inventory/item-product/adjust
POST http://localhost:3000/api/mini-inventory/stock-inbound/change-status

Katalog Action Lengkap (Complete Action Catalog)

CRUD Standar (Standard CRUD)

ActionMethodFungsi
/datatablesPOSTData list dengan pagination, search, dan sort (format DataTables.net)
/createPOSTInsert satu record baru
/updatePOSTUpdate satu record berdasarkan primary key
/deletePOSTHapus satu record berdasarkan primary key
/firstPOSTAmbil detail satu record berdasarkan primary key
/lookupGET / POSTData untuk autocomplete/dropdown (format {id, text})
/readPOSTData universal dengan pagination, WHERE kompleks, dan kolom selektif

Pengambilan Data Lanjutan (Advanced Data Retrieval)

ActionMethodFungsi
/aggregatePOSTFungsi agregasi (COUNT, SUM, AVG, MIN, MAX, GROUP BY, HAVING)

Endpoint /lookup mendukung dua HTTP method: GET dengan header X-Request-Mode: dynamic untuk pencarian real-time (autocomplete), dan POST dengan header X-Request-Mode: static untuk memuat seluruh data dropdown atau data dengan filter.

Operasi Khusus (Special Operations)

ActionMethodFungsi
/adjustPOSTAtomic increment/decrement field numerik

CRUD Composite

ActionMethodFungsi
/create-compositePOSTBuat header + detail items dalam satu transaksi
/read-compositePOSTBaca header beserta detail items
/update-compositePOSTUpdate header + insert/update/delete detail items

Export dan Import

ActionMethodFungsi
/exportPOSTTrigger async export job ke Excel
/export-statusGETPolling status export job
/export-downloadGETDownload file Excel hasil export
/import-uploadPOSTUpload file Excel (multipart/form-data)
/import-previewPOSTValidasi dan preview data import
/import-commitPOSTEksekusi INSERT/UPDATE ke database
/import-statusGETPolling status import job

Workflow

ActionMethodFungsi
/change-statusPOSTPerubahan status record dengan validasi transisi dan hook

Resource Lock

ActionMethodFungsi
/lock/acquirePOSTMengunci satu atau lebih record
/lock/releasePOSTMelepas kunci record
/lock/statusPOSTMengecek status kunci record

Pemetaan Action ke Payload (Action-to-Payload Mapping)

Setiap action diaktifkan melalui property action di file payload. Beberapa action memerlukan konfigurasi tambahan:

ActionProperty di actionKonfigurasi Tambahan
/datatablesdatatables: truedatatablesQuery, datatablesWhere
/createcreate: truefieldValidation (opsional)
/updateupdate: truefieldValidation (opsional)
/deletedelete: true—
/firstfirst: trueviewQuery, viewName (opsional)
/lookuplookup: truefieldNameLookup (opsional)
/readread: trueviewQuery, viewName (opsional)
/adjustadjust: trueadjustConfig
/aggregateaggregate: trueaggregateConfig
/create-compositecreateComposite: truemasterDetail
/read-compositereadComposite: truemasterDetail
/update-compositeupdateComposite: truemasterDetail
/exportexport: trueexportQuery, columnFormats (opsional)
/import-*import: trueimportConfig
/change-statuschangeStatus: trueworkflow

Konvensi Penamaan (Naming Conventions)

KomponenKonvensiContoh
Projectkebab-casemini-inventory, hr-system
Endpointlowercase, underscore untuk multi-wordsupplier, stock_inbound, item_product
Actionlowercase, hyphen untuk multi-wordcreate, create-composite, import-upload

Nama endpoint ditentukan oleh nama file payload (tanpa ekstensi .json). File supplier.json menghasilkan endpoint supplier, file stock_inbound.json menghasilkan endpoint stock_inbound.

Langkah Selanjutnya (Next Steps)

  • Format Response untuk memahami struktur response yang dikembalikan oleh setiap action
  • Pola Action-Based untuk memahami filosofi di balik pendekatan action-based

On this page

Format URL Universal (Universal URL Format)Contoh URL (URL Examples)Katalog Action Lengkap (Complete Action Catalog)CRUD Standar (Standard CRUD)Pengambilan Data Lanjutan (Advanced Data Retrieval)Operasi Khusus (Special Operations)CRUD CompositeExport dan ImportWorkflowResource LockPemetaan Action ke Payload (Action-to-Payload Mapping)Konvensi Penamaan (Naming Conventions)Langkah Selanjutnya (Next Steps)