208 lines
7.4 KiB
Plaintext
208 lines
7.4 KiB
Plaintext
API Spec - Identity & Authorization API (Bahasa Indonesia)
|
|
|
|
Ringkasan
|
|
--------
|
|
Spesifikasi berikut disesuaikan dengan controller aktual pada aplikasi: modul Auth (OIDC + internal JWT), modul Identity (Users, Roles, Permissions) dan mekanisme otorisasi berbasis permission.
|
|
|
|
Base URL
|
|
--------
|
|
- https://api.example.com
|
|
|
|
Header Umum & Auth
|
|
------------------
|
|
- Content-Type: application/json
|
|
- Accept: application/json
|
|
- Otentikasi dapat diberikan dalam dua cara:
|
|
1) Cookie internal (default flow):
|
|
- raylab_jwt (internal JWT, httpOnly cookie)
|
|
- raylab_refresh (internal refresh token, httpOnly cookie)
|
|
2) Authorization header: Bearer <internal_jwt>
|
|
- Banyak endpoint melindungi akses dengan JWT dan permission checks. Respons sukses dari controller umumnya dibungkus sebagai:
|
|
{ "success": true, "data": ..., "meta": { ... } }
|
|
|
|
Auth (modul /auth)
|
|
-------------------
|
|
1) GET /auth/login
|
|
- Deskripsi: Mulai flow Authorization Code + PKCE. Redirect (302) ke Identity Provider.
|
|
- Query params:
|
|
- returnTo (optional) - URL tujuan setelah login
|
|
- Response: 302 Redirect
|
|
|
|
2) GET /auth/callback
|
|
- Deskripsi: Endpoint callback OIDC. Menukarkan code/state, membuat internal JWT & refresh token, dan menyetel cookie httpOnly.
|
|
- Response: 302 Redirect ke returnTo atau '/'
|
|
- Cookie yang disetel:
|
|
- raylab_jwt (internal JWT, maxAge sesuai expiresIn)
|
|
- raylab_refresh (refresh token)
|
|
|
|
3) POST /auth/logout
|
|
- Deskripsi: Invalidate internal refresh token (opsional) dan redirect ke logout identity provider.
|
|
- Body (optional): { "refreshToken": "..." }
|
|
- Response: 302 Redirect
|
|
|
|
4) POST /auth/refresh
|
|
- Deskripsi: Tukar refresh token menjadi internal JWT baru.
|
|
- Input: refresh token di cookie raylab_refresh atau di body { "refreshToken": "..." }
|
|
- Response 200: { "success": true, "data": { "accessToken": "...", "expiresIn": 3600, ... } }
|
|
|
|
5) GET /auth/me
|
|
- Deskripsi: Ambil data user saat ini dari internal JWT (cookie atau Authorization header).
|
|
- Response 200: { "success": true, "data": { /* user object */ } }
|
|
|
|
Catatan: tidak ada endpoint "/auth/register" atau POST /auth/login berbasis email/password pada controller saat ini — login terjadi via OIDC dan internal session cookies.
|
|
|
|
Users (modul /users)
|
|
--------------------
|
|
Semua endpoint Users dijalankan di bawah guards: JwtAuthGuard, CurrentUserGuard dan PermissionGuard. Respons mengikuti format { success, data, meta }.
|
|
|
|
1) GET /users
|
|
- Permission: PermissionType.USER_READ
|
|
- Deskripsi: List pengguna (paged)
|
|
- Query params umum: page, per_page, sort, q
|
|
- Response 200:
|
|
{ "success": true, "data": [ /* user list (toResponse) */ ], "meta": { "total": 123 } }
|
|
|
|
2) GET /users/me
|
|
- Deskripsi: Ambil profil user saat ini (token harus ada di cookie atau header)
|
|
- Response 200: { "success": true, "data": { /* current user */ }, "meta": {} }
|
|
|
|
3) GET /users/:id
|
|
- Permission: PermissionType.USER_READ
|
|
- Deskripsi: Ambil user berdasarkan id
|
|
- Response 200: { "success": true, "data": { /* user */ }, "meta": {} }
|
|
- 404 jika tidak ditemukan
|
|
|
|
4) PATCH /users/:id/enable
|
|
- Permission: PermissionType.USER_UPDATE
|
|
- Deskripsi: Enable user
|
|
- Response 200: { "success": true, "data": { /* updated user */ }, "meta": {} }
|
|
|
|
5) PATCH /users/:id/disable
|
|
- Permission: PermissionType.USER_UPDATE
|
|
- Deskripsi: Disable user
|
|
- Response 200
|
|
|
|
6) PATCH /users/:id
|
|
- Permission: PermissionType.USER_UPDATE
|
|
- Deskripsi: Update profil user (body berisi fields yang diperbolehkan)
|
|
- Body contoh: { "name": "Nama Baru", "email": "baru@example.com" }
|
|
- Response 200: { "success": true, "data": { /* updated user */ }, "meta": {} }
|
|
|
|
7) DELETE /users/:id
|
|
- Permission: PermissionType.USER_DELETE
|
|
- Deskripsi: Soft delete user
|
|
- Response 200: { "success": true, "data": null, "meta": {} }
|
|
|
|
8) POST /users/:id/restore
|
|
- Permission: PermissionType.USER_UPDATE
|
|
- Deskripsi: Restore user yang di-soft-delete
|
|
- Response 200: { "success": true, "data": { /* restored user */ }, "meta": {} }
|
|
|
|
Roles (modul /roles)
|
|
--------------------
|
|
Semua route dilindungi oleh JwtAuthGuard, CurrentUserGuard dan PermissionGuard.
|
|
|
|
1) GET /roles
|
|
- Permission: PermissionType.ROLE_READ
|
|
- Deskripsi: List roles
|
|
- Query params: page, per_page, q
|
|
- Response 200: { "success": true, "data": [ /* roles */ ], "meta": { "total": 10 } }
|
|
|
|
2) GET /roles/:id
|
|
- Permission: PermissionType.ROLE_READ
|
|
- Deskripsi: Ambil role
|
|
- Response 200
|
|
|
|
3) POST /roles
|
|
- Permission: PermissionType.ROLE_CREATE
|
|
- Deskripsi: Buat role baru
|
|
- Body contoh: { "name": "editor", "description": "..." }
|
|
- Response 200: { "success": true, "data": { /* created role */ }, "meta": {} }
|
|
|
|
4) PATCH /roles/:id
|
|
- Permission: PermissionType.ROLE_UPDATE
|
|
- Deskripsi: Update role
|
|
- Response 200
|
|
|
|
5) DELETE /roles/:id
|
|
- Permission: PermissionType.ROLE_DELETE
|
|
- Deskripsi: Hapus role
|
|
- Response 200: { "success": true, "data": null, "meta": {} }
|
|
|
|
6) POST /roles/:id/permissions
|
|
- Permission: PermissionType.ROLE_UPDATE
|
|
- Deskripsi: Assign permission ke role
|
|
- Body: { "permissionId": "..." }
|
|
- Response 200: { "success": true, "data": { /* updated role */ }, "meta": {} }
|
|
|
|
7) DELETE /roles/:id/permissions/:permissionId
|
|
- Permission: PermissionType.ROLE_UPDATE
|
|
- Deskripsi: Remove permission dari role
|
|
- Response 200
|
|
|
|
Permissions (modul /permissions)
|
|
-------------------------------
|
|
Semua route dilindungi oleh JwtAuthGuard, CurrentUserGuard dan PermissionGuard.
|
|
|
|
1) GET /permissions
|
|
- Permission: PermissionType.PERMISSION_READ
|
|
- Deskripsi: List permissions
|
|
- Response 200: { "success": true, "data": [ /* permissions */ ], "meta": { "total": 20 } }
|
|
|
|
2) GET /permissions/:id
|
|
- Permission: PermissionType.PERMISSION_READ
|
|
- Deskripsi: Ambil permission
|
|
- Response 200
|
|
|
|
3) POST /permissions
|
|
- Permission: PermissionType.PERMISSION_CREATE
|
|
- Deskripsi: Buat permission baru
|
|
- Body contoh: { "name": "user:create", "description": "..." }
|
|
- Response 200: { "success": true, "data": { /* created */ }, "meta": {} }
|
|
|
|
4) PATCH /permissions/:id
|
|
- Permission: PermissionType.PERMISSION_UPDATE
|
|
- Deskripsi: Update permission
|
|
- Response 200
|
|
|
|
5) DELETE /permissions/:id
|
|
- Permission: PermissionType.PERMISSION_DELETE
|
|
- Deskripsi: Delete permission
|
|
- Response 200: { "success": true, "data": null, "meta": {} }
|
|
|
|
Format Tanggal dan Numerik
|
|
--------------------------
|
|
- Tanggal/waktu: ISO 8601 (UTC), contoh: "2024-08-01T12:34:56Z"
|
|
- Desimal: titik sebagai pemisah desimal, misal 125000.50
|
|
|
|
Pagination
|
|
----------
|
|
- Gunakan page & per_page
|
|
- Meta object pada controller ini biasanya minimal: { total }
|
|
|
|
Response Error Umum
|
|
-------------------
|
|
- 400 Bad Request - payload tidak valid
|
|
{
|
|
"success": false,
|
|
"error": "invalid_request",
|
|
"message": "Deskripsi kesalahan",
|
|
"details": { "field": ["pesan validasi"] }
|
|
}
|
|
- 401 Unauthorized - token tidak ada/invalid/expired
|
|
- 403 Forbidden - tidak cukup izin
|
|
- 404 Not Found
|
|
- 429 Too Many Requests - rate limit
|
|
- 500 Internal Server Error
|
|
|
|
Keamanan dan Persyaratan
|
|
------------------------
|
|
- Semua permintaan harus lewat HTTPS (TLS 1.2+)
|
|
- Gunakan cookie httpOnly (raylab_jwt / raylab_refresh) untuk flow internal atau header Authorization: Bearer <token>
|
|
- Validasi input di server (length, tipe, range)
|
|
- Sanitasi data untuk mencegah injection
|
|
|
|
Catatan Akhir
|
|
------------
|
|
- Spesifikasi ini disesuaikan dengan controller yang ada: /auth, /users, /roles, /permissions dan mekanisme otorisasi berbasis PermissionType.
|
|
- Perhatikan bahwa detail field respons (mis. bentuk toResponse pada entitas) dapat berbeda antar resource. Untuk integrasi, gunakan endpoint /auth/me dan /users/me untuk memvalidasi data user yang tersedia. |