Integration API

Integration API memberi sistem eksternal akses langsung ke baris sebuah tabel tanpa melalui antarmuka CMS. Gunakan untuk menyinkronkan data dari aplikasi lain, mengotomatiskan pembaruan baris lewat script, atau menghubungkan pipeline yang mengisi tabel secara terjadwal.

Setiap tabel (collection) memiliki sepasang API key sendiri, yaitu primary key dan secondary key, untuk pengelolaan yang terpisah.

Buka Tools → Plugins → Dynamic Table → Tables, buka tabel, lalu masuk ke tab Integration untuk menemukan API key dan dokumentasi endpoint.

Autentikasi

Semua request Integration API harus menyertakan API key di header request:

X-Secret-Key: <primary-or-secondary-key>

Primary key dan secondary key dapat dipakai secara bergantian. Gunakan satu untuk integrasi utama Anda dan simpan yang lain sebagai cadangan untuk rotasi key.

API key hanya berlaku untuk satu tabel. Key untuk satu tabel tidak dapat dipakai untuk mengakses tabel lain.

Base URL

Semua endpoint Integration API mengikuti struktur berikut:

{plugin-host}/api/dynamic-table/integration/{agentId}/{configurationId}/{collectionId}

Nilai agentId, configurationId, dan collectionId ditampilkan di tab Integration untuk tabel Anda.

Endpoint

Mengambil Semua Baris

Ambil daftar baris dari tabel secara berhalaman.

GET /api/dynamic-table/integration/{agentId}/{configurationId}/{collectionId}

Query parameter:

Response: Array objek baris, masing-masing berisi id baris, rowNumber, dan dictionary data berisi pasangan nama kolom dan nilai.

Mengambil Satu Baris

Ambil satu baris berdasarkan ID barisnya.

GET /api/dynamic-table/integration/{agentId}/{configurationId}/{collectionId}/{rowId}

Response: Satu objek baris dengan id, rowNumber, dan data.

Menambahkan Baris Secara Massal

Tambahkan beberapa baris baru dalam satu request.

POST /api/dynamic-table/integration/{agentId}/{configurationId}/{collectionId}/bulk

Request body:

{
  "rows": [
    { "column_name_1": "value", "column_name_2": 123 },
    { "column_name_1": "another value", "column_name_2": 456 }
  ]
}

Setiap baris dalam array adalah dictionary nama kolom ke nilai. Nama kolom harus sama dengan nama kolom internal (snake_case) yang didefinisikan di skema tabel.

Aturan validasi:

• Kolom wajib harus memiliki nilai.
• Nilai primary key harus unik di dalam request dan belum ada di tabel.
• Nilai harus sesuai dengan tipe kolomnya.

Response: Daftar baris yang dibuat beserta id dan rowNumber yang ditetapkan.

Memperbarui Baris Secara Massal

Perbarui beberapa baris dalam satu request berdasarkan ID baris.

PUT /api/dynamic-table/integration/{agentId}/{configurationId}/{collectionId}/bulk

Request body:

{
  "rows": [
    { "id": "row-uuid-1", "data": { "status": "active", "score": 99 } },
    { "id": "row-uuid-2", "data": { "status": "inactive" } }
  ]
}

Hanya kolom yang disertakan di data yang diperbarui. Kolom yang tidak disertakan di payload tetap mempertahankan nilainya saat ini.

Response: Daftar baris yang diperbarui.

Menghapus Baris Secara Massal

Hapus beberapa baris dalam satu request berdasarkan ID baris.

DELETE /api/dynamic-table/integration/{agentId}/{configurationId}/{collectionId}/bulk

Request body:

{
  "rowIds": ["row-uuid-1", "row-uuid-2", "row-uuid-3"]
}

Response: HTTP 204 No Content jika berhasil.

Merotasi API Key

Jika sebuah API key bocor atau Anda perlu mencabut akses untuk integrasi tertentu, rotasi key tersebut:

1. Buka tab Integration milik tabel.
2. Klik Refresh Primary Key atau Refresh Secondary Key.
3. Konfirmasi rotasi.

Key lama langsung tidak berlaku. Perbarui integrasi Anda agar memakai key baru sebelum melakukan rotasi.

Merotasi secondary key saat primary key sedang aktif dipakai (atau sebaliknya) memungkinkan rotasi tanpa downtime sama sekali.

Contoh: Menambahkan Baris Massal dengan curl

curl -X POST "https://your-plugin-host/api/dynamic-table/integration/agent-123/config-456/collection-789/bulk" \
  -H "X-Secret-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "product_name": "Laptop Pro 14", "category": "Electronics", "price": 4500, "in_stock": true },
      { "product_name": "Wireless Mouse", "category": "Accessories", "price": 89, "in_stock": true }
    ]
  }'

Catatan

• Baris yang ditambahkan atau diperbarui lewat Integration API di-embed dan diindeks secara otomatis. Tidak perlu memicu pembuatan ulang embedding untuk operasi per baris.
• Integration API menerapkan validasi skema yang sama dengan antarmuka CMS. Tipe yang tidak cocok dan field wajib yang kosong akan mengembalikan 400 Bad Request beserta detailnya.
• Integration API tidak membutuhkan plugin token (JWT). API ini hanya memakai API key yang berlaku untuk collection tersebut.

Halaman Terkait

• Manage Data: menambah dan mengedit baris secara manual dari CMS.
• Import and Export: memuat baris secara massal dari file.
• Create a Table: melihat nama kolom yang dipakai di payload API.
• Dynamic Table Overview