# 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.