Serving API

Memulai

Serving API menyajikan tabel-tabel platform lakehouse kepada aplikasi. Setiap resource (misalnya sdgs/publikasi) adalah satu tabel, dengan nama kolom yang sama persis dengan tabel gold sumbernya. Resource di bawah /raw ditandai raw: tabel bronze, yaitu data sistem sumber persis seperti dikirimnya, tanpa dibersihkan dan tanpa key (misalnya /raw/pdunsri/krs_mahasiswa). Data disalin ke serving store setiap kali tabel sumbernya selesai dibangun, dan meta.as_of pada setiap respons menyatakan kapan tabel terakhir diperbarui.

Base URL

https://api.ranah.durianworks.my.id/v1

Path endpoint di dokumentasi ini relatif terhadap base URL: /sdgs/publikasi berarti https://api.ranah.durianworks.my.id/v1/sdgs/publikasi. Dokumen OpenAPI ada di https://api.ranah.durianworks.my.id/v1/openapi.json; halaman ini dan halaman-halaman lainnya menjelaskan apa yang tidak muat di dalamnya.

API key

Setiap aplikasi memegang satu API key, diterbitkan oleh pengelola platform atas nama aplikasi itu dengan tujuan penggunaan yang dicatat. Key berawalan lh_ dan hanya diperlihatkan sekali, saat diterbitkan; simpan di tempat yang aman (secret store aplikasi Anda, bukan di kode atau repository).

Kirim key pada setiap request sebagai bearer token:

Authorization: Bearer lh_...

Tanpa key, atau dengan key yang tidak dikenal atau sudah dicabut, responsnya 401 dengan header WWW-Authenticate.

Secara opsional, kirim header X-Actor berisi identitas pengguna akhir di sisi aplikasi Anda (paling banyak 100 karakter). Nilainya dicatat di log request dan tidak memengaruhi otorisasi; key tetap milik aplikasi.

Request pertama

curl -H "Authorization: Bearer lh_..." \
  "https://api.ranah.durianworks.my.id/v1/sdgs/publikasi?page_size=5"

Responsnya JSON dengan tiga bagian: data (array baris), page (halaman, ukuran halaman, total baris yang cocok), dan meta (as_of).

Satu baris berdasarkan key-nya:

curl -H "Authorization: Bearer lh_..." \
  "https://api.ranah.durianworks.my.id/v1/sdgs/publikasi/{id_publikasi}"

Scope

Setiap API key membawa daftar scope; setiap resource memerlukan satu scope. Resource dari satu sistem sumber dapat berbagi scope: sdgunsri membuka semua resource di bawah /sdgs, dan mahasiswa membuka /mahasiswa, /aktivitas_kuliah_mahasiswa, /biaya_kuliah_mahasiswa_aktif, /biaya_kuliah_fakultas, serta /biaya_kuliah_program_studi untuk keperluan keuangan internal, dan raw:pdunsri membuka semua resource raw PD Unsri di bawah /raw/pdunsri. Request dengan key yang tidak memiliki scope yang diperlukan dijawab 403 dengan keterangan scope apa yang dimiliki key itu.

Rate limit

Setiap key punya jatah request per menit. Melewati jatah itu dijawab 429 dengan header Retry-After (detik) dan keterangan berapa lama menunggu. Respons yang berhasil tidak membawa header rate limit; hitung dari sisi aplikasi bila perlu, dan hormati Retry-After saat menerimanya.

Selanjutnya

  • Sintaks query: filter, sort, dan pagination.
  • Katalog: setiap tabel yang disajikan punya halamannya sendiri, dengan deskripsi, setiap kolomnya, dan endpoint yang tersedia — get all, dan get by key bila key-nya satu kolom. Misalnya sdg dan publikasi.
  • Error: bentuk dan arti setiap respons error.
  • Penggunaan data: apa yang diharapkan dari aplikasi pemegang API key.