Kontrak HTTP API

Mounting

API memiliki health endpoint /healthz, root /, dan router aplikasi pada /api. Domain router yang tersedia saat ini mencakup system, auth, geography, dan organization.

GET /healthz
GET /api
GET /api/v1/health
GET /api/v1/meta

Header wajib

Accept: application/json
Content-Type: application/json
x-request-id: <uuid>
Authorization: Bearer <token>

Authorization digunakan oleh client yang memiliki bearer token. Server terpercaya dapat meneruskan identitas memakai proxy secret; secret tidak boleh dikirim ke browser atau mobile.

Status code

Status	Makna
200/201	Request berhasil
400	Payload atau query tidak valid
401	Session/token tidak ada atau kedaluwarsa
403	User tidak memiliki akses
404	Resource tidak ditemukan dalam scope
415	Content type bukan JSON
429	Rate limit terlampaui
500	Error internal; jangan bocorkan stack trace

Error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body is invalid",
    "requestId": "req_123"
  }
}

Client membaca error.code untuk perilaku UI dan memakai requestId untuk debugging.