web-antrean/HAK_AKSES_API_ENDPOINT.md

API Endpoint Documentation - Hak Akses

Deskripsi

Dokumentasi ini menjelaskan semua API endpoint yang diperlukan untuk fitur Hak Akses di halaman /pages/Setting/HakAkses.vue. Endpoint-endpoint ini akan dihubungkan ke backend API yang disediakan oleh tim backend.

---

Base URL

{API_BASE_URL}/api/v1

Catatan: Ganti {API_BASE_URL} dengan URL backend yang sebenarnya (contoh: http://10.10.150.131:8089)

---

1. Get List Users

Mengambil daftar semua users beserta roles, groups, dan informasi lainnya yang diperlukan untuk form hak akses.

Endpoint

GET /api/users/list

Request

Headers:

Content-Type: application/json
Accept: application/json

Query Parameters: Tidak ad

Response

Success (200 OK):

[
  {
    "id": "user-123",
    "namaLengkap": "John Doe",
    "namaUser": "johndoe",
    "email": "john.doe@example.com",
    "tipeUser": "Super Admin",
    "lastLogin": 1704067200,
    "roles": ["superadmin", "admin"],
    "realmRoles": ["default-roles-sandbox"],
    "accountRoles": [],
    "resourceRoles": [],
    "groups": [
      "/Instalasi STIM/Devops/Superadmin",
      "/Instalasi STIM/Admin"
    ],
    "given_name": "John",
    "family_name": "Doe",
    "createdAt": 1704067200,
    "updatedAt": 1704067200
  }
]

Error (500 Internal Server Error):

{
  "statusCode": 500,
  "statusMessage": "Failed to fetch users"
}

Field Description

• id: Unique identifier user
• namaLengkap: Nama lengkap user
• namaUser: Username untuk login
• email: Email user
• tipeUser: Tipe/jenis user (contoh: "Super Admin", "Admin Loket", dll)
• lastLogin: Timestamp terakhir login (Unix timestamp dalam detik)
• roles: Array of role names
• realmRoles: Array of realm roles dari Keycloak
• accountRoles: Array of account roles
• resourceRoles: Array of resource roles
• groups: Array of group paths (contoh: "/Instalasi STIM/Devops/Superadmin")
• given_name: Nama depan
• family_name: Nama belakang
• createdAt: Timestamp pembuatan (Unix timestamp dalam detik)
• updatedAt: Timestamp update terakhir (Unix timestamp dalam detik)

---

2. Get Permissions by Role and Group

Mengambil daftar permissions dari backend berdasarkan role dan group yang dipilih.

Endpoint

GET /api/v1/permission

Request

Headers:

Content-Type: application/json
Accept: application/json

Query Parameters:

Parameter	Type	Required	Description
roles	string	Yes	Role name (contoh: "superadmin", "admin")
groups	string	Yes	Group name atau group path (contoh: "STIM", "/Instalasi STIM/Devops/Superadmin")

Example:

GET /api/v1/permission?roles=superadmin&groups=STIM

Response

Success (200 OK):

{
  "message": "Data permission berhasil diambil",
  "data": [
    {
      "id": 1,
      "create": false,
      "read": true,
      "update": false,
      "disable": false,
      "delete": false,
      "active": true,
      "pagename": "Halaman Utama",
      "pagesID": 1,
      "level": 1,
      "sort": 1,
      "parent": null
    },
    {
      "id": 2,
      "create": false,
      "read": true,
      "update": false,
      "disable": false,
      "delete": false,
      "active": true,
      "pagename": "Pengaturan",
      "pagesID": 2,
      "level": 1,
      "sort": 2,
      "parent": null
    },
    {
      "id": 3,
      "create": true,
      "read": true,
      "update": true,
      "disable": true,
      "delete": false,
      "active": true,
      "pagename": "Hak Akses",
      "pagesID": 3,
      "level": 2,
      "sort": 3,
      "parent": 2
    }
  ],
  "meta": {
    "count": 3,
    "total": 3
  }
}

Error (400 Bad Request):

{
  "statusCode": 400,
  "statusMessage": "roles or groups parameter is required"
}

Error (500 Internal Server Error):

{
  "message": "Failed to fetch permissions",
  "data": [],
  "meta": {
    "count": 0,
    "total": 0
  }
}

Field Description

• id: Unique identifier permission
• create: Boolean, permission untuk create/tambah data
• read: Boolean, permission untuk read/lihat data
• update: Boolean, permission untuk update/edit data
• disable: Boolean, permission untuk disable/nonaktifkan
• delete: Boolean, permission untuk delete/hapus data
• active: Boolean, status aktif permission
• pagename: Nama halaman/menu (akan di-mapping ke menu sidebar)
• pagesID: ID halaman di sistem backend
• level: Level hierarki menu (1 = parent, 2 = child, dll)
• sort: Urutan tampil
• parent: ID parent menu (null jika parent menu)

---

3. Get List Hak Akses

Mengambil daftar semua hak akses yang sudah tersimpan.

Endpoint

GET /api/v1/hak-akses

Request

Headers:

Content-Type: application/json
Accept: application/json

Query Parameters: Tidak ada

Response

Success (200 OK):

[
  {
    "id": 1,
    "userId": "user-123",
    "namaLengkap": "John Doe",
    "namaUser": "johndoe",
    "tipeUser": "Super Admin",
    "role": "superadmin",
    "group": "STIM",
    "groupPath": "/Instalasi STIM/Devops/Superadmin",
    "namaTipeUser": "Super Admin",
    "hakAksesMenu": [
      {
        "name": "Dashboard",
        "canAccess": true,
        "canView": true,
        "canAdd": false,
        "canEdit": false,
        "canDelete": false
      },
      {
        "name": "Master Data",
        "canAccess": true,
        "canView": true,
        "canAdd": true,
        "canEdit": true,
        "canDelete": false
      }
    ],
    "isGroupBased": true,
    "createdAt": 1704067200,
    "updatedAt": 1704067200
  }
]

Error (500 Internal Server Error):

{
  "statusCode": 500,
  "statusMessage": "Failed to fetch hak akses"
}

Field Description

• id: Unique identifier hak akses
• userId: ID user (optional, untuk backward compatibility)
• namaLengkap: Nama lengkap user (optional)
• namaUser: Username (optional)
• tipeUser: Tipe user (optional)
• role: Role name (required)
• group: Group name (required)
• groupPath: Full group path (optional, untuk group-based access)
• namaTipeUser: Nama tipe user (optional)
• hakAksesMenu: Array of menu permissions
  • name: Nama menu
  • canAccess: Boolean, apakah bisa akses menu
  • canView: Boolean, apakah bisa lihat data
  • canAdd: Boolean, apakah bisa tambah data
  • canEdit: Boolean, apakah bisa edit data
  • canDelete: Boolean, apakah bisa hapus data
• isGroupBased: Boolean, apakah hak akses ini group-based (true) atau individual (false)
• createdAt: Timestamp pembuatan (Unix timestamp dalam detik)
• updatedAt: Timestamp update terakhir (Unix timestamp dalam detik)

---

4. Create Hak Akses

Membuat hak akses baru (group-based atau individual).

Endpoint

POST /api/v1/hak-akses

Request

Headers:

Content-Type: application/json
Accept: application/json

Body:

{
  "role": "superadmin",
  "group": "STIM",
  "groupPath": "/Instalasi STIM/Devops/Superadmin",
  "namaTipeUser": "Super Admin",
  "hakAksesMenu": [
    {
      "name": "Dashboard",
      "canAccess": true,
      "canView": true,
      "canAdd": false,
      "canEdit": false,
      "canDelete": false
    },
    {
      "name": "Master Data",
      "canAccess": true,
      "canView": true,
      "canAdd": true,
      "canEdit": true,
      "canDelete": false
    }
  ],
  "isGroupBased": true
}

Response

Success (201 Created):

{
  "success": true,
  "message": "Hak akses berhasil dibuat",
  "data": {
    "id": 1,
    "role": "superadmin",
    "group": "STIM",
    "groupPath": "/Instalasi STIM/Devops/Superadmin",
    "namaTipeUser": "Super Admin",
    "hakAksesMenu": [
      {
        "name": "Dashboard",
        "canAccess": true,
        "canView": true,
        "canAdd": false,
        "canEdit": false,
        "canDelete": false
      }
    ],
    "isGroupBased": true,
    "createdAt": 1704067200,
    "updatedAt": 1704067200
  }
}

Error (400 Bad Request):

{
  "statusCode": 400,
  "statusMessage": "role and group are required"
}

Error (409 Conflict):

{
  "statusCode": 409,
  "statusMessage": "Hak akses untuk group dan role ini sudah ada"
}

Field Description

Required Fields:

• role: Role name (string, required)
• group: Group name (string, required)
• hakAksesMenu: Array of menu permissions (array, required)

Optional Fields:

• userId: ID user (string, optional)
• namaLengkap: Nama lengkap (string, optional)
• namaUser: Username (string, optional)
• tipeUser: Tipe user (string, optional)
• groupPath: Full group path (string, optional)
• namaTipeUser: Nama tipe user (string, optional)
• isGroupBased: Boolean, default true (boolean, optional)

---

5. Update Hak Akses

Mengupdate hak akses yang sudah ada.

Endpoint

PATCH /api/v1/hak-akses/{id}

Request

Headers:

Content-Type: application/json
Accept: application/json

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	ID hak akses yang akan diupdate

Body (semua field optional, hanya kirim field yang ingin diupdate):

{
  "role": "admin",
  "group": "LOKET",
  "namaTipeUser": "Admin Loket",
  "hakAksesMenu": [
    {
      "name": "Dashboard",
      "canAccess": true,
      "canView": true,
      "canAdd": false,
      "canEdit": false,
      "canDelete": false
    }
  ]
}

Response

Success (200 OK):

{
  "success": true,
  "message": "Hak akses berhasil diperbarui",
  "data": {
    "id": 1,
    "role": "admin",
    "group": "LOKET",
    "groupPath": "/Instalasi STIM/Loket",
    "namaTipeUser": "Admin Loket",
    "hakAksesMenu": [
      {
        "name": "Dashboard",
        "canAccess": true,
        "canView": true,
        "canAdd": false,
        "canEdit": false,
        "canDelete": false
      }
    ],
    "isGroupBased": true,
    "createdAt": 1704067200,
    "updatedAt": 1704067300
  }
}

Error (400 Bad Request):

{
  "statusCode": 400,
  "statusMessage": "ID is required"
}

Error (404 Not Found):

{
  "statusCode": 404,
  "statusMessage": "Hak akses not found"
}

Error (500 Internal Server Error):

{
  "statusCode": 500,
  "statusMessage": "Failed to update hak akses"
}

---

6. Delete Hak Akses

Menghapus hak akses.

Endpoint

DELETE /api/v1/hak-akses/{id}

Request

Headers:

Content-Type: application/json
Accept: application/json

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	ID hak akses yang akan dihapus

Response

Success (200 OK):

{
  "success": true,
  "message": "Hak akses berhasil dihapus"
}

Error (400 Bad Request):

{
  "statusCode": 400,
  "statusMessage": "ID is required"
}

Error (404 Not Found):

{
  "statusCode": 404,
  "statusMessage": "Hak akses not found"
}

Error (500 Internal Server Error):

{
  "statusCode": 500,
  "statusMessage": "Failed to delete hak akses"
}

---

Mapping Permissions ke Menu Sidebar

Sistem akan otomatis memetakan pagename dari API permission ke nama menu di sidebar. Mapping dilakukan dengan:

1. Exact match: pagename.toLowerCase() === menu.name.toLowerCase()
2. Partial match: pagename.toLowerCase().includes(menu.name.toLowerCase()) atau sebaliknya

Contoh Mapping:

• pagename: "Halaman Utama" → Menu: "Dashboard"
• pagename: "Pengaturan" → Menu: "Master Data"
• pagename: "Hak Akses" → Menu: "Hak Akses"

Permission Mapping:

• read: true → canView: true
• create: true → canAdd: true
• update: true → canEdit: true
• delete: true → canDelete: true
• active: true || read: true → canAccess: true

---

Group-Based Access

Sistem mendukung Group-Based Access dimana:

• Satu hak akses dapat diberikan ke semua user yang memiliki group dan role yang sama
• Setiap user dapat memiliki multiple hak akses dari berbagai group
• Hak akses disimpan dengan flag isGroupBased: true dan groupPath untuk identifikasi

Contoh:

Jika hak akses dibuat dengan:

• role: "superadmin"
• groupPath: "/Instalasi STIM/Devops/Superadmin"
• isGroupBased: true

Maka semua user yang memiliki:

• Role: "superadmin" DAN
• Group: "/Instalasi STIM/Devops/Superadmin"

Akan otomatis mendapatkan hak akses tersebut.

---

Error Handling

Semua endpoint harus mengembalikan error dengan format konsisten:

{
  "statusCode": 400|404|409|500,
  "statusMessage": "Error message description"
}

HTTP Status Codes:

• 200 OK: Request berhasil
• 201 Created: Resource berhasil dibuat
• 400 Bad Request: Request tidak valid (missing required fields, invalid format)
• 404 Not Found: Resource tidak ditemukan
• 409 Conflict: Resource sudah ada (untuk create duplicate)
• 500 Internal Server Error: Server error

---

Authentication

Catatan: Tim backend perlu menentukan apakah endpoint-endpoint ini memerlukan authentication token atau tidak. Jika diperlukan, tambahkan:

Headers:

Authorization: Bearer {access_token}

---

Testing

Contoh Request dengan cURL:

1. Get Users List:

curl -X GET "http://{API_BASE_URL}/api/users/list" \
  -H "Content-Type: application/json"

2. Get Permissions:

curl -X GET "http://{API_BASE_URL}/api/v1/permission?roles=superadmin&groups=STIM" \
  -H "Content-Type: application/json"

3. Create Hak Akses:

curl -X POST "http://{API_BASE_URL}/api/v1/hak-akses" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "superadmin",
    "group": "STIM",
    "groupPath": "/Instalasi STIM/Devops/Superadmin",
    "namaTipeUser": "Super Admin",
    "hakAksesMenu": [
      {
        "name": "Dashboard",
        "canAccess": true,
        "canView": true,
        "canAdd": false,
        "canEdit": false,
        "canDelete": false
      }
    ],
    "isGroupBased": true
  }'

4. Update Hak Akses:

curl -X PATCH "http://{API_BASE_URL}/api/v1/hak-akses/1" \
  -H "Content-Type: application/json" \
  -d '{
    "namaTipeUser": "Updated Admin",
    "hakAksesMenu": [...]
  }'

5. Delete Hak Akses:

curl -X DELETE "http://{API_BASE_URL}/api/v1/hak-akses/1" \
  -H "Content-Type: application/json"

---

Catatan Penting

1. Base URL: Ganti {API_BASE_URL} dengan URL backend yang sebenarnya
2. Timestamps: Semua timestamp menggunakan format Unix timestamp (detik sejak epoch)
3. Group Path: Group path harus full path (contoh: "/Instalasi STIM/Devops/Superadmin") untuk group-based access
4. Menu Permissions: Array hakAksesMenu harus sesuai dengan struktur menu sidebar
5. Validation: Backend harus melakukan validasi untuk:
   • Required fields (role, group, hakAksesMenu)
   • Duplicate check untuk group+role combination (jika isGroupBased = true)
   • Format data yang valid

---

Kontak

Jika ada pertanyaan atau perubahan requirement, silakan hubungi tim frontend.