API (JSON)

Dokumentasi alur REST-like di bawah prefix /api: isi routes/api.php, gerbang ApiController, delegasi otomatis ke controllers/Api/ tanpa harus menambah satu baris route per controller (kecuali endpoint khusus yang harus didahulukan). Contoh konkret: Api\TestController.

routes/api.php · ApiController · nodeApiControllerData() · controllers/Api/

Alur baca backend

Routing → Web Applications → API (halaman ini).

API SDK runtime (Web, Node.js, Electron, React Native)

Untuk klien aplikasi, header Authorization terdaftar, upload multipart, dan gateway Forge / Outside, gunakan indeks SDK runtime — gambaran & matriks beserta halaman per controller (menu di kanan).

Peran `routes/api.php`

Berkas ini mendefinisikan URL yang bukan ditangkap oleh pola umum, atau yang membutuhkan method HTTP tetap (mis. hanya POST).

Route eksplisit — contoh di proyek: /api/google-signin, /api/register, dll., langsung ke Api\GoogleAuthController@…. Letakkan di atas route generik.
Route generik — tiga baris penangkap: $router->any('/api', …), any('/api/', …), any('/api/{params}', …) semuanya ke ApiController@index. Inilah yang membuat endpoint baru di App\Controllers\Api\FooController dapat diakses sebagai /api/foo/… tanpa menambah entri baru di api.php (selama tidak bentrok dengan route spesifik di atasnya).

Aturan urutan: di api.php tertulis: route spesifik harus di atas route generik /api/{params}, supaya tidak “ketelan” oleh ApiController@index.

routes/api.php (struktur)

// 1) Endpoint khusus (spesifik)
$router->add('/api/google-signin', 'Api/GoogleAuthController@signin', ['POST']);
// …

// 2) Penangkap umum (di bawah)
$router->any('/api', 'ApiController@index');
$router->any('/api/', 'ApiController@index');
$router->any('/api/{params}', 'ApiController@index');

Apa yang dilakukan `ApiController::index()`

Semua request yang jatuh ke route generik di atas masuk ke App\Controllers\ApiController::index(). Ringkasan perilaku (lihat kode di controllers/ApiController.php):

Preflight CORS — jika OPTIONS tanpa header Authorization, balas header CORS standar dan 200, lalu exit.
Header respons — untuk request biasa: Content-Type: application/json; charset=UTF-8 dan header CORS permisif (Access-Control-Allow-Origin: *, dll.).
Menentukan “halaman” API — dari $params['page'] atau slug setelah /api/ (mis. /api/test → nama controller test). Mendukung bentuk controller/method dalam satu segmen params.
Mode SDK — jika ada header Authorization yang cocok baris di tabel production, alihkan ke SdkController (bukan dokumentasi TestController; itu jalur kredensial aplikasi).
Delegasi — jika ada Authorization atau kelas App\Controllers\Api\{Page}Controller ada (controllerExistsData), panggil nodeApiControllerData() di NexaController; hasil array di-json() ke klien. Jika controller tidak ada → JSON 404. Eksepsi → JSON 500.

Tanpa mendaftar per controller (otomatis)

Selama URL tidak tertangkap route lebih spesifik di atas, pola /api/ diproses ApiController@index → nodeApiControllerData() → instansiasi App\Controllers\Api\NamaController (huruf: Nama di-ucfirst).

Contoh: berkas controllers/Api/TestController.php otomatis melayani prefix /api/test tanpa menambah $router->add('/api/test', …) di api.php.

Pemetaan HTTP → method di `nodeApiControllerData()`

Di system/NexaController.php, method PHP yang dipanggil ditentukan oleh: (1) nama method di URL (slug kedua setelah controller, mis. /api/test/hello → hello), jika ada dan method tersebut ada di controller; (2) jika tidak, fallback dari verb HTTP ke nama method internal:

HTTP	Fallback method (jika tidak ada slug method)
`GET`	`index`
`POST`	`created`
`PUT`	`red` (nama internal di framework; bukan typo)
`PATCH`	`patch`
`DELETE`	`deleted`
`OPTIONS`	`options` (biasanya sudah ditangani preflight di ApiController)

Method API yang mengembalikan data harus mengembalikan array (atau nilai yang kemudian dibungkus). Parameter isi body: nodeApiControllerData memanggil handler dengan getRequestData() (satu argumen) atau ($getRequestData(), $controllerParams) jika signature method membutuhkan dua argumen — lihat refleksi di kode.

`Api\TestController` — referensi method

Berkas: controllers/Api/TestController.php. Namespace App\Controllers\Api. Dipakai untuk percobaan klien (Postman, fetch) dan sebagai contoh bentuk respons JSON.

Method PHP	Fungsi	Cara memanggil (contoh)
`index(): array`	Respons sukses sederhana dengan `greeting` dan `timestamp`.	`GET /api/test` (tanpa sub-method → fallback GET = `index`)
`hello(): array`	Sama seperti `index` secara isi (pesan “Hello from API!”).	`GET /api/test/hello`
`error(): array`	Contoh payload dengan `status: error` dan `error_code` (untuk uji format error di klien).	`GET /api/test/error`
`created($data, $params): array`	Contoh “resource dibuat”; mengembalikan body + `params` yang diteruskan.	`POST /api/test` (fallback POST → `created`)
`red($data, $params): array`	Contoh operasi terkait `PUT` (framework memetakan PUT → nama method `red`).	`PUT /api/test`
`updated($data, $params): array`	Contoh “data diperbarui”; tidak otomatis dari PATCH — panggil eksplisit lewat path, mis. `/api/test/updated` dengan verb yang cocok, atau tambahkan method `patch` di controller jika ingin memakai `PATCH` sesuai fallback framework.	mis. `GET /api/test/updated` atau sesuaikan kebutuhan
`deleted($data, $params): array`	Contoh “resource dihapus”.	`DELETE /api/test` (fallback DELETE → `deleted`)

PUT vs updated: secara bawaan, verb PUT memanggil method red() di TestController, bukan updated(). Gunakan updated hanya jika Anda memetakan URL eksplisit atau menambah method patch/red sesuai konvensi Anda.

PATCH vs patch: fallback HTTP PATCH memanggil method PHP bernama patch(). TestController saat ini tidak punya patch(), jadi PATCH /api/test (tanpa slug method yang ada) akan gagal di nodeApiControllerData() (biasanya terlihat sebagai error 500 di JSON). Tambahkan public function patch(…) di controller Anda jika ingin mendukung PATCH dengan pola bawaan.

Contoh respons (GET /api/test)

{
  "status": "success",
  "message": "Hello from API!",
  "timestamp": 1710000000,
  "greeting": "Hello World!"
}

404 & 500 dari ApiController

404 — controller App\Controllers\Api\{Page}Controller tidak ada dan tidak memenuhi jalur SDK dengan Authorization.
500 — pengecualian saat menjalankan controller / encode JSON.

Nxdom Framework

API (JSON)

Alur baca backend

API SDK runtime (Web, Node.js, Electron, React Native)

Peran routes/api.php

Apa yang dilakukan ApiController::index()