Referensi Integrasi API v1 (API v1 Reference)

Antarmuka Pemrograman Integrasi DeweStream (Integration API v1) dirancang bagi pengembang sistem backend (seperti plugin kursus LMS, server web sekolah online, atau aplikasi manajemen konten mandiri) untuk menyinkronkan data video secara aman langsung dari akun Member.

API v1 Reference

Karakteristik Utama API v1

1. Khusus Komunikasi Antar-Server (Server-to-Server): Kunci integrasi digunakan dari backend Anda, bukan dari browser pengunjung atau siswa.
2. Katalog Bersifat Read-Only: API v1 hanya menyediakan akses baca untuk video berstatus ready (siap putar) dan tidak berada di dalam Trash, pohon folder, serta profil akun pemilik kunci.
3. Bukan Pengganti Token Pemutaran: API ini mengembalikan metadata katalog dan status kesiapan embed (embed readiness). API tidak mengirimkan file media mentah (raw media), kunci enkripsi video, token pemutaran jangka pendek, atau share link publik (public share URL).
4. Tidak Melakukan Mutasi Konten: Tidak ada endpoint untuk meng-upload file baru, mengedit metadata, menghapus video, atau membuat share link publik melalui API v1.
5. Independen dari Sesi Dashboard: Autentikasi menggunakan token Bearer terpisah. Logout dari dashboard Member tidak mencabut kunci API backend.

Konfigurasi Teknis Dasar

• Base URL Produksi: https://app.dewe.stream (atau domain instalasi yang ditetapkan pada lingkungan Anda).
• Awalan Rute API: /api/integrations/v1
• Format Data: JSON (Content-Type: application/json; charset=utf-8)
• Header Keamanan Respons: Seluruh endpoint menyertakan Cache-Control: private, no-store.

Autentikasi

Setiap permintaan ke Integration API v1 wajib menyertakan header HTTP Authorization dengan skema Bearer:

Authorization: Bearer dws_a1b2c3d4e5f6.AbCdEfGhIjKlMnOpQrStUvWxYz_0123456789aBcDeF

• String kunci terdiri dari prefiks publik (misal: dws_a1b2c3d4e5f6) dan token rahasia acak 43 karakter yang dipisahkan oleh tanda titik (.).
• Kunci dibuat melalui dashboard Member di menu Account → kartu API access.
• Jika header Authorization tidak disertakan, berformat salah, atau kunci telah dicabut (revoked), server akan mengembalikan respons HTTP 401 Unauthorized:

{
  "error": {
    "code": "integration_unauthorized",
    "message": "Integration authentication failed"
  },
  "requestId": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}

Batas Frekuensi Panggilan (Rate Limiting)

Untuk menjaga stabilitas layanan:

• Setiap kunci API memiliki kuota kecepatan maksimal 120 permintaan per menit.
• Jika batas kuota terlampaui dalam jendela 60 detik, server akan mengembalikan respons HTTP 429 Too Many Requests beserta header HTTP Retry-After: 60:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many Integration API requests"
  },
  "requestId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

Backend Anda disarankan menyimpan (cache) hasil katalog video secara lokal dan menghormati waktu tunggu pada header Retry-After.

Daftar Endpoint API v1

1. Memeriksa Identitas & Hak Akses Akun (GET /me)

Mengembalikan identitas Member pemilik kunci dan kapabilitas yang aktif.

• Metode: GET
• Path: /api/integrations/v1/me
• Header: Authorization: Bearer <secret>

Contoh Respons Sukses (HTTP 200)

{
  "data": {
    "memberId": "11111111-2222-4333-8444-555555555555",
    "displayName": "Akun Demo Kreator",
    "capabilities": {
      "videoCatalog": true,
      "folderCatalog": true,
      "write": false
    }
  }
}

2. Membaca Daftar Video (GET /videos)

Mengambil daftar video milik Member yang berstatus ready dan tidak berada di dalam Trash, diurutkan dari yang terbaru diperbarui (updatedAt menurun).

• Metode: GET
• Path: /api/integrations/v1/videos
• Parameter Kueri (Query Parameters):
  • query (string, opsional): Kata kunci pencarian judul (maksimal 160 karakter, pencarian substring tidak peka huruf besar-kecil).
  • folderId (string UUID, opsional): Batasi hasil hanya pada video yang berada langsung di dalam folder ini.
  • limit (integer, opsional): Jumlah maksimal data per halaman. Nilai antara 1 hingga 50 (standar: 20).
  • cursor (string base64url, opsional): Kursor penanda posisi halaman berikutnya yang diperoleh dari nilai meta.nextCursor halaman sebelumnya.

Contoh Respons Sukses (HTTP 200)

{
  "data": [
    {
      "id": "7a3b4c5d-6e7f-4a1b-8c2d-3e4f5a6b7c8d",
      "title": "Modul 1: Pengenalan Pembelajaran",
      "durationSeconds": 754,
      "folder": {
        "id": "e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
        "name": "Bab 1 Dasar",
        "path": "Kursus Utama / Bab 1 Dasar"
      },
      "thumbnail": {
        "available": true
      },
      "embed": {
        "videoId": "7a3b4c5d-6e7f-4a1b-8c2d-3e4f5a6b7c8d",
        "readiness": "ready"
      },
      "updatedAt": "2026-10-05T08:30:00.000Z"
    }
  ],
  "meta": {
    "nextCursor": "eyJ1cGRhdGVkQXQiOiIyMDI2LTEwLTA1VDA4OjMwOjAwLjAwMFoiLCJpZCI6IjdhM2I0YzVkLTZlN2YtNGExYi04YzJkLTNlNGY1YTZiN2M4ZCJ9"
  }
}

3. Membaca Detail Satu Video (GET /videos/:id)

Mengambil rincian katalog untuk satu video tertentu.

• Metode: GET
• Path: /api/integrations/v1/videos/{id}
• Parameter Path: {id} adalah UUID unik file video.

Respons Jika Ditemukan (HTTP 200)

Mengembalikan objek tunggal di dalam pembungkus { "data": { ... } } dengan struktur bidang yang sama persis seperti pada daftar video.

Respons Jika Tidak Ditemukan (HTTP 404)

Jika video tidak ada, bukan milik akun Anda, belum selesai diproses (processing/failed), atau berada di Trash:

{
  "error": {
    "code": "video_not_found",
    "message": "Video not found"
  },
  "requestId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}

4. Membaca Status Kumpulan Video Secara Batch (POST /videos/resolve)

Memeriksa ketersediaan dan mengambil metadata untuk banyak video sekaligus dalam satu panggilan jaringan (operasi baca batch, bukan mutasi).

• Metode: POST
• Path: /api/integrations/v1/videos/resolve
• Header: Content-Type: application/json
• Badan Permintaan (Request Body):

{
  "ids": [
    "7a3b4c5d-6e7f-4a1b-8c2d-3e4f5a6b7c8d",
    "00000000-0000-4000-8000-000000000099"
  ]
}

Contoh Respons (HTTP 200)

Urutan elemen pada array respons dipastikan sama persis dengan urutan ID yang Anda kirimkan. Video yang tidak tersedia (karena telah dihapus, masuk Trash, atau bukan milik akun Anda) ditandai dengan objek { id, state: "unavailable" }:

{
  "data": [
    {
      "id": "7a3b4c5d-6e7f-4a1b-8c2d-3e4f5a6b7c8d",
      "title": "Modul 1: Pengenalan Pembelajaran",
      "durationSeconds": 754,
      "folder": null,
      "thumbnail": {
        "available": true
      },
      "embed": {
        "videoId": "7a3b4c5d-6e7f-4a1b-8c2d-3e4f5a6b7c8d",
        "readiness": "ready"
      },
      "updatedAt": "2026-10-05T08:30:00.000Z"
    },
    {
      "id": "00000000-0000-4000-8000-000000000099",
      "state": "unavailable"
    }
  ]
}

5. Membaca Struktur Pohon Folder (GET /folders)

Mengambil seluruh folder video milik Member yang tersusun dalam jalur hierarkis.

• Metode: GET
• Path: /api/integrations/v1/folders

Contoh Respons Sukses (HTTP 200)

{
  "data": [
    {
      "id": "e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
      "parentFolderId": null,
      "name": "Kursus Utama",
      "path": "Kursus Utama"
    },
    {
      "id": "f2a3b4c5-6d7e-4f8a-9b0c-1d2e3f4a5b6c",
      "parentFolderId": "e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
      "name": "Bab 1 Dasar",
      "path": "Kursus Utama / Bab 1 Dasar"
    }
  ]
}

Panduan Pengujian & Checklist Penerimaan Integrasi

Gunakan panduan 10 langkah berikut untuk memverifikasi kesiapan integrasi backend Anda secara terstruktur.

Prasyarat Pengujian

1. Gunakan akun demo atau lingkungan pengujian (staging) khusus.
2. Buat variabel lingkungan pada terminal penguji agar rahasia tidak tersimpan di riwayat baris perintah (shell history):

# Masukkan base URL instalasi sasaran
export DEWESTREAM_BASE_URL="https://app.dewe.stream"

# Masukkan secret kunci API melalui prompt tersembunyi
read -s -p "Masukkan Kunci API: " DEWESTREAM_API_KEY
echo ""

10 Langkah Pengujian Penerimaan (Acceptance Checklist)

Setelah pengujian selesai, bersihkan variabel dari lingkungan terminal Anda:

unset DEWESTREAM_API_KEY
unset DEWESTREAM_BASE_URL

Panduan Terkait

• Akses Kunci API di Dashboard
• Batas Sesi Dashboard Akun
• Kode Embed Video (Embed)