Init

2026-07-30 09:41:42 +07:00
parent aef8e412a8
commit 3efac50f39
70 changed files with 3217 additions and 0 deletions
@@ -0,0 +1,289 @@
+# 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:
+
+``` text
+/api/v1/
+```
+
+Contoh:
+
+``` text
+/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:
+
+``` http
+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:
+
+``` text
+/users/{id}/groups
+/users/{id}/sessions
+/groups/{id}/roles
+/domains/{id}/resources
+```
+
+Action endpoint:
+
+``` text
+/users/{id}/reset-password
+/users/{id}/special-access
+/users/{id}/groups
+```
+
+------------------------------------------------------------------------
+
+# Standard Response
+
+## Success
+
+``` json
+{
+  "success": true,
+  "data": {},
+  "meta": {
+    "requestId": "...",
+    "timestamp": "..."
+  }
+}
+```
+
+## Error
+
+``` json
+{
+  "success": false,
+  "error": {
+    "code": "USER_NOT_FOUND",
+    "message": "User not found"
+  }
+}
+```
+
+Semua endpoint wajib menggunakan format yang sama.
+
+------------------------------------------------------------------------
+
+# Pagination
+
+Request:
+
+``` text
+GET /users?page=1&limit=20
+```
+
+Response:
+
+``` json
+{
+  "success": true,
+  "data": [],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 125,
+    "totalPages": 7
+  }
+}
+```
+
+------------------------------------------------------------------------
+
+# Filtering
+
+Contoh:
+
+``` text
+/users?group=Owner
+/applications?status=online
+```
+
+------------------------------------------------------------------------
+
+# Sorting
+
+``` text
+/users?sort=name
+/users?sort=-createdAt
+```
+
+Tanda minus (`-`) berarti urutan menurun (descending).
+
+------------------------------------------------------------------------
+
+# Search
+
+``` text
+/users?search=ray
+```
+
+Pencarian dilakukan melalui query parameter, bukan endpoint terpisah.
+
+------------------------------------------------------------------------
+
+# API Versioning
+
+Versi API menjadi bagian dari URL.
+
+Contoh:
+
+``` text
+/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:
+
+``` text
+/internal/jobs
+/internal/sync
+```
+
+Internal API tidak boleh diekspos ke publik.
+
+------------------------------------------------------------------------
+
+# Request ID
+
+Setiap request memiliki Request ID unik.
+
+Header:
+
+``` text
+X-Request-ID
+```
+
+Request ID digunakan untuk:
+
+-   Audit
+-   Logging
+-   Debugging
+-   Distributed tracing
+
+------------------------------------------------------------------------
+
+# Idempotency
+
+Operasi tertentu mendukung:
+
+``` text
+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.