Skip to main content

Konvensi API (payload & response)

Dokumen ini menjadi acuan format request/response untuk endpoint Bitwewe.

Base path​

  • API v1: /api/...
  • language: mempengaruhi lokalisasi pesan error/sukses (ApiRequest akan setLocale berdasarkan header ini).

Validasi payload (Request class)​

Mayoritas endpoint memakai kelas turunan App\Http\Requests\Api\ApiRequest yang:

  • memvalidasi input via rules()
  • mensanitasi via filters() (jika didefinisikan oleh request)
  • mengembalikan error HTTP 400 saat validasi gagal (satu pesan pertama)

Envelope response (global)​

Semua controller API memakai sendResponse() / sendError() yang membungkus response menggunakan App\Utils\ResponseUtil.

Sukses​

Struktur minimal:

{
  "code": 200,
  "title": "OK",
  "message": "…",
  "result": true,
  "data": {}
}

Catatan:

  • Field data hanya ada jika controller mengembalikan data non-null.

Gagal​

Struktur:

{
  "code": 400,
  "title": "Bad Request",
  "message": "…",
  "result": false,
  "auth_required": true
}

Catatan:

  • auth_required kadang di-set false untuk error login tertentu (lihat AuthController v1).

Status code yang sering dipakai​

  • 400: validasi gagal / user tidak ditemukan / error umum
  • 401: kredensial salah / refresh token invalid
  • 403: akses ditolak (suspend, OTP salah, refresh token ditolak, dll.)
  • 411: email belum terverifikasi (konvensi aplikasi ini)