290 lines
4.8 KiB
Markdown
290 lines
4.8 KiB
Markdown
# 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.
|