#Menggunakan API Key di NocoBase

Panduan ini mendemonstrasikan cara menggunakan API Key di NocoBase untuk mendapatkan data melalui contoh "todo" yang nyata. Ikuti petunjuk langkah demi langkah berikut untuk memahami alur kerja yang lengkap.

#1 Memahami API Key

API Key adalah token keamanan yang digunakan untuk memvalidasi API Request dari pengguna yang berwenang. Ia berfungsi sebagai kredensial untuk memvalidasi identitas pemohon saat mengakses sistem NocoBase melalui aplikasi web, aplikasi mobile, atau skrip backend.

Format pada header HTTP Request:

Authorization: Bearer {API Key}

Awalan "Bearer" menunjukkan bahwa setelahnya adalah API Key terautentikasi yang digunakan untuk memvalidasi izin pemohon.

#Skenario Penggunaan Umum

API Key biasanya digunakan dalam skenario berikut:

1. Akses aplikasi klien: browser web dan aplikasi mobile menggunakan API Key untuk memvalidasi identitas pengguna, memastikan hanya pengguna yang berwenang yang dapat mengakses data.
2. Eksekusi tugas otomatis: proses background dan tugas terjadwal menggunakan API Key untuk melakukan operasi pembaruan, sinkronisasi data, dan pencatatan log secara aman.
3. Pengembangan dan pengujian: developer menggunakan API Key selama debugging dan pengujian untuk meniru request terautentikasi dan memvalidasi respons API.

API Key memberikan beberapa keuntungan keamanan: validasi identitas, pemantauan penggunaan, pembatasan laju request, dan pencegahan ancaman, memastikan operasi NocoBase yang stabil dan aman.

#2 Membuat API Key di NocoBase

#2.1 Aktifkan Plugin Autentikasi: API Key

Pastikan Plugin Autentikasi: API Key bawaan sudah diaktifkan. Setelah diaktifkan, halaman konfigurasi API Key baru akan muncul pada pengaturan sistem.

#2.2 Buat Tabel Data Pengujian

Untuk tujuan demonstrasi, buat tabel data bernama todos dengan field-field berikut:

• id
• judul (title)
• selesai (completed)

Tambahkan beberapa record contoh ke tabel data:

• Makan
• Tidur
• Main game

#2.3 Buat dan Tetapkan Peran

API Key terikat pada peran pengguna; sistem menentukan izin request berdasarkan peran yang ditetapkan. Sebelum membuat API Key, Anda harus membuat peran dan mengkonfigurasi izin yang sesuai. Buat peran bernama "Peran API Todo" dan beri akses penuh ke tabel data todos.

Jika "Peran API Todo" tidak tersedia saat membuat API Key, pastikan pengguna saat ini telah ditetapkan peran ini:

Setelah peran ditetapkan, refresh halaman dan navigasikan ke halaman manajemen API Key. Klik "Tambahkan API Key" untuk memverifikasi bahwa "Peran API Todo" muncul pada pemilihan peran.

Untuk kontrol akses yang lebih baik, pertimbangkan untuk membuat akun pengguna khusus (misalnya "Pengguna API Todo") khusus untuk manajemen dan pengujian API Key. Tetapkan "Peran API Todo" ke pengguna ini.

#2.4 Hasilkan dan Simpan API Key

Setelah formulir disubmit, sistem akan menampilkan pesan konfirmasi dan API Key yang baru dihasilkan. Catatan Penting: segera salin dan simpan key ini dengan aman; karena alasan keamanan, key ini tidak akan ditampilkan lagi.

Contoh API Key:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M

#2.5 Catatan Penting

• Masa berlaku API Key ditentukan oleh pengaturan kedaluwarsa yang dikonfigurasi saat pembuatan.
• Pembuatan dan validasi API Key bergantung pada variabel lingkungan APP_KEY. Jangan modifikasi variabel ini, jika tidak semua API Key yang ada di sistem akan tidak berlaku.

#3 Pengujian Autentikasi API Key

#3.1 Menggunakan Plugin Dokumentasi API

Buka Plugin Dokumentasi API, lihat metode request, URL, parameter, dan header untuk setiap endpoint API.

#3.2 Memahami Operasi CRUD Dasar

NocoBase menyediakan API CRUD (Create, Read, Update, Delete) standar untuk operasi data:

• Query daftar (antarmuka list):

  GET {baseURL}/{collectionName}:list
  Header:
  - Authorization: Bearer <API Key>
  

• Tambahkan record (antarmuka create):

  POST {baseURL}/{collectionName}:create
  
  Header:
  - Authorization: Bearer <API Key>
  
  Body request (format JSON), contoh:
      {
          "title": "123"
      }

• Modifikasi record (antarmuka update):

  POST {baseURL}/{collectionName}:update?filterByTk={id}
  Header:
  - Authorization: Bearer <API Key>
  
  Body request (format JSON), contoh:
      {
          "title": "123",
          "completed": true
      }

• Hapus record (antarmuka delete):

  POST {baseURL}/{collectionName}:destroy?filterByTk={id}
  Header:
  - Authorization: Bearer <API Key>

Dimana:

• {baseURL}: URL sistem NocoBase
• {collectionName}: nama tabel data

Contoh: instance lokal localhost:13000, nama tabel data todos:

http://localhost:13000/api/todos:list

#3.3 Pengujian dengan Postman

Buat GET Request di Postman dengan konfigurasi sebagai berikut:

• URL: endpoint request (misalnya http://localhost:13000/api/todos:list)
• Headers: tambahkan header Authorization dengan nilai:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M

Respons sukses:

{
    "data": [
        {
            "createdAt": "2025-03-03T09:57:36.728Z",
            "updatedAt": "2025-03-03T09:57:36.728Z",
            "completed": null,
            "createdById": 1,
            "id": 1,
            "title": "eat food",
            "updatedById": 1
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "pageSize": 20,
        "totalPage": 1
    }
}

Respons error (API Key tidak valid/kedaluwarsa):

{
    "errors": [
        {
            "message": "Your session has expired. Please sign in again.",
            "code": "INVALID_TOKEN"
        }
    ]
}

Pemecahan Masalah: jika autentikasi gagal, validasi izin peran, binding API Key, dan format token.

#3.4 Ekspor Kode Request

Postman memungkinkan ekspor request dalam berbagai format. Contoh perintah cURL:

curl --location 'http://localhost:13000/api/todos:list' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M'

#4 Menggunakan API Key di JS Block

NocoBase 2.0 mendukung penulisan kode JavaScript native langsung pada halaman menggunakan JS Block. Contoh ini mendemonstrasikan cara menggunakan API Key untuk mendapatkan data API eksternal.

#Buat JS Block

Tambahkan JS Block pada halaman NocoBase dan gunakan kode berikut untuk mendapatkan data todo:

// Gunakan API Key untuk mendapatkan data todo
async function fetchTodos() {
  try {
    // Tampilkan tip loading
    ctx.message.loading('Sedang mengambil data...');

    // Muat library axios untuk HTTP Request
    const axios = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/axios@1.6.0/dist/axios.min.js');

    if (!axios) {
      ctx.message.error('Gagal memuat library HTTP');
      return;
    }

    // API Key (ganti dengan API Key Anda yang sebenarnya)
    const apiKey = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M';

    // Inisiasi API Request
    const response = await axios.get('http://localhost:13000/api/todos:list', {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });

    // Tampilkan hasil
    console.log('Daftar todo:', response.data);
    ctx.message.success(`Berhasil mendapatkan ${response.data.data.length} record`);

    // Anda dapat memproses data di sini
    // Contoh: tampilkan ke tabel, update field formulir, dll.

  } catch (error) {
    console.error('Error mengambil data:', error);
    ctx.message.error('Gagal mengambil data: ' + error.message);
  }
}

// Eksekusi fungsi
fetchTodos();

#Poin Penting

• ctx.requireAsync(): muat library eksternal secara dinamis (seperti axios) untuk HTTP Request
• ctx.message: tampilkan notifikasi pengguna (pesan loading, sukses, error)
• Autentikasi API Key: teruskan API Key di header Authorization dengan awalan Bearer
• Penanganan respons: proses data yang dikembalikan sesuai kebutuhan (tampilkan, transformasi, dll.)

#5 Ringkasan

Panduan ini mencakup alur kerja lengkap penggunaan API Key di NocoBase:

1. Persiapan: aktifkan Plugin API Key dan buat tabel data pengujian
2. Konfigurasi: buat peran dengan izin yang sesuai dan hasilkan API Key
3. Pengujian: validasi autentikasi API Key dengan Postman dan Plugin Dokumentasi API
4. Integrasi: gunakan API Key di JS Block

Sumber daya tambahan:

• Dokumentasi Plugin API Key
• Plugin Dokumentasi API