RayLab-Core/Docs/Phase-06-API-Architecture.md

RayLab Core Phase 6 --- API Architecture

Tujuan

Fase 6 mendefinisikan standar API RayLab Core sebagai kontrak komunikasi untuk seluruh aplikasi dalam ekosistem RayLab.

API harus konsisten, mudah dipahami, terdokumentasi, dan stabil untuk jangka panjang.

---

Prinsip API

Seluruh API RayLab Core mengikuti prinsip berikut:

• RESTful
• Stateless
• Versioned
• Consistent
• Predictable
• Self Documented
• API First

---

Base URL

Seluruh endpoint menggunakan format:

/api/v1/

Contoh:

/api/v1/users
/api/v1/groups
/api/v1/domains
/api/v1/applications
/api/v1/media
/api/v1/storage

---

HTTP Method

Method Fungsi

---

GET Membaca data POST Membuat data PATCH Memperbarui sebagian data PUT Mengganti seluruh data (jika diperlukan) DELETE Soft delete

---

Resource-Oriented API

Contoh endpoint User:

GET /api/v1/users
GET /api/v1/users/{id}
POST /api/v1/users
PATCH /api/v1/users/{id}
DELETE /api/v1/users/{id}

Nested resource:

/users/{id}/groups
/users/{id}/sessions
/groups/{id}/roles
/domains/{id}/resources

Action endpoint:

/users/{id}/reset-password
/users/{id}/special-access
/users/{id}/groups

---

Standard Response

Success

{
  "success": true,
  "data": {},
  "meta": {
    "requestId": "...",
    "timestamp": "..."
  }
}

Error

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User not found"
  }
}

Semua endpoint wajib menggunakan format yang sama.

---

Pagination

Request:

GET /users?page=1&limit=20

Response:

{
  "success": true,
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 125,
    "totalPages": 7
  }
}

---

Filtering

Contoh:

/users?group=Owner
/applications?status=online

---

Sorting

/users?sort=name
/users?sort=-createdAt

Tanda minus (-) berarti urutan menurun (descending).

---

Search

/users?search=ray

Pencarian dilakukan melalui query parameter, bukan endpoint terpisah.

---

API Versioning

Versi API menjadi bagian dari URL.

Contoh:

/api/v1/
/api/v2/

Perubahan besar tidak boleh merusak kompatibilitas client lama.

---

Public API dan Internal API

Public API

Digunakan oleh:

• Web Admin
• Android
• CLI
• Future Client

Internal API

Digunakan oleh:

• Background Job
• Scheduler
• Adapter
• Internal Service

Contoh:

/internal/jobs
/internal/sync

Internal API tidak boleh diekspos ke publik.

---

Request ID

Setiap request memiliki Request ID unik.

Header:

X-Request-ID

Request ID digunakan untuk:

• Audit
• Logging
• Debugging
• Distributed tracing

---

Idempotency

Operasi tertentu mendukung:

Idempotency-Key

Hal ini mencegah duplikasi request akibat retry jaringan.

---

Dokumentasi API

Seluruh endpoint harus didokumentasikan menggunakan Swagger (OpenAPI).

Minimal mencakup:

• Summary
• Description
• Request DTO
• Response DTO
• Error Response

Tidak boleh ada endpoint tanpa dokumentasi.

---

Aturan API

• Tidak ada endpoint tanpa versioning.
• Tidak ada endpoint tanpa validasi DTO.
• Tidak ada endpoint tanpa dokumentasi.
• Seluruh endpoint menghasilkan response yang konsisten.
• Controller tidak berisi business logic.
• Error menggunakan kode yang konsisten.

---

Hasil Akhir Fase 6

Pada akhir fase ini RayLab Core memiliki standar API yang menjadi kontrak komunikasi resmi untuk seluruh aplikasi dalam ekosistem RayLab.

Dokumen ini menjadi acuan implementasi Controller, DTO, Service, dokumentasi Swagger, dan integrasi seluruh client dengan RayLab Core.