Panduan API Dapodik
A. UmumUntuk tujuan integrasi dengan sistem eksternal, sistem Dapodik menyediakan layanan komunikasi dengan memanfaatkan web service API (Application Programming Interface). Dengan memanfaatkan layanan komunikasi ini, sistem lain bisa memanfaatkan data-data yang tersedia dalam Dapodik untuk kepentingannya masing-masing. Walaupun demikian, mengingat Dapodik masih dalam tahap pengumpulan dan verifikasi data, untuk sementara layanan ini hanya bersifat searah dan read-only (baca saja). Ke depan, layanan komunikasi ini akan terus dikembangkan dengan menambah fitur modifikasi (insert, delete, update) dan format komunikasi yang lebih beragam (XML, JSON, dan lain sebagainya).
B. Spesifikasi Komunikasi
1. Komunikasi
Protocol HTTP (Hyper Text Transfer Protocol)
Method GET
Hostname operator.dapodik.org
Port 80
Path /dapodik/api.php
2. Pengenalan Pengguna
Layanan ini membutuhkan satu parameter masukan yang harus berisi nilai benar dan valid, untuk kepentingan otentikasi pengguna layanan. Input yang diharapkan bernama passport yang harus selalu disertakan setiap kali akan mengakses layanan Dapodik API (mandatory request parameter). Nilai passport yang benar dan harus digunakan dalam request-request API selanjutnya diperoleh dari proses login dimana nilai tersebut hanya akan valid dan diakui selama sesi login pengguna yang bersangkutan masih aktif.
3. Document Output Format
Format yang disediakan ada 2 macam yaitu INI/CONF atau JSON. Macam format yang dihasilkan diatur melalui parameter format pada masing-masing request.
Masing-masing keluaran diperlihatkan pada bagian OUTPUT pada masing-masing layanan yang tersedia, dengan susunan format INI/CONF terlebih dahulu kemudian diikuti dengan format keluaran JSON.
Untuk format INI atau CONF adalah daftar pasangan nama dan nilai ("name=value" pair) dengan EOL di tiap pasangan sedang untuk JSON bisa mengacu pada laman berikut format JSON.
C. Layanan yang Tersedia
Jangan lupa menambahkan parameter input passport dalam setiap request! Penulisan Keterangan Pembacaan
diapit petik ganda nilai tetap atau konstanta, gunakan apa adanya tanpa tanda petik.
diapit kurung siku nilai masukan atau keluaran, berisi nilai yang benar dan sesuai.
diakhiri bintang nilai masukan opsional, bisa diisi, bisa diabaikan.
1. Login
INPUT:
data "login"
username
passport
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
passport= {"passport": }
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
Sesi login akan terus aktif selama masih ada aktifitas request dalam session id yang bersangkutan. Sesi akan secara otomatis menjadi non-aktif (auto logout) jika tidak ada aktifitas request hingga 30 menit setelah login yang terakhir.
2. Daftar Seluruh Propinsi di Indonesia
INPUT:
data "propinsi"
passport
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
=
... {"kode_propinsi":, ... }
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
3. Daftar Seluruh Kota/Kabupaten dalam Propinsi
INPUT:
data "kota"
passport
propinsi
kota*
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
=
... {"kode_kota":, ... }
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
4. Daftar Sekolah dalam Kota/Kabupaten
INPUT:
data "npsn"
passport
propinsi
kota
jenjang
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
=
... {"npsn":, ... }
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-propinsi Lingkup propinsi tidak diijinkan {"status": "error-propinsi"} Lingkup propinsi tidak diijinkan
status=error-kota Lingkup kota tidak diijinkan {"status": "error-kota"} Lingkup kota tidak diijinkan
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
Kode jenjang yang dikenali:
•1 : SD
•2 : SMP
•3 : SMA/SMK
•4 : Perguruan Tinggi
•9 : Lain-lain
5. Informasi Sekolah Berdasarkan NPSN
INPUT:
data "npsn"
passport
sekolah
propinsi
kota
jenjang*
status*
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
=
status=
jenjang=
propinsi=
kota=
alamat= {"npsn": ,
"status":,
"jenjang":,
"propinsi":,
"kota":,
"alamat":}
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
Kode status yang dikenali:
•1 : Negeri
•2 : Swasta
•6 : Kejuruan negeri
•7 : Kejuruan swasta
•8 : Negeri di bawah Kementerian Agama
•9 : Swasta di bawah Kementerian Agama
6.a. Daftar Siswa dalam Sekolah
INPUT:
data "nisn"
passport
sekolah
lulus* < 0
1 > (opsional, default = 0, 0 = daftar siswa aktif, 1 = daftar siswa berstatus lulus)
rev* < 0
1 > (opsional, default = 0)
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
•rev = 0:
=
...
•rev = 0:
{"nisn": {"tgl_lahir":, "tingkat_kelas": , "nama_siswa": , "alamat_rumah": }, ... }
•rev = 1:
=
...
•rev = 1:
{"nisn": {"tmp_lahir":, "tgl_lahir": , "kelamin": , "tingkat_kelas": , "nama_siswa": , "alamat_rumah": }, ... }
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
6.b. Detil Siswa
INPUT:
data "nisn"
passport
siswa
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
=
... {"nisn": {"nama":, "sekolah_id": }, ... }
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
7. Daftar Guru dalam Sekolah
INPUT:
data "nign"
passport
sekolah
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
=
... {"nign": {"tgl_lahir":, "nama_guru": , "alamat_rumah": }, ... }
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
8. Logout
INPUT:
data "logout"
passport
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
status=logout {"status": "logout"}
PESAN KESALAHAN:
status=error-layanan Kesalahan isi dari parameter data
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
D. Sinkronisasi Data
Layanan API Dapodik sementara hanya menyediakan data secara spesifik dalam lingkup tertentu. Untuk melakukan sinkronisasi data dalam jumlah besar (bulk), harus dilakukan dengan mekanisme perulangan terhadap layanan-layanan yang telah disediakan. Misal, untuk melakukan sinkronisasi data siswa dalam satu kota/kabupaten, bisa dilakukan dalam urutan berikut:
1.Ambil daftar sekolah dalam kota/kabupaten yang dimaksud. Akan lebih baik jika proses ini dipecah sejumlah kode jenjang yang dikenali agar tidak terlalu membebani server Dapodik.
2.Lakukan sinkronisasi data sekolah di database lokal berdasarkan hasil kembalian dari langkah [1].
3.Ambil daftar siswa untuk setiap sekolah berdasarkan hasil kembalian dari langkah [1].
4.Lakukan sinkronisasi data siswa di database lokal berdasarkan hasil kembalian dari langkah [3].
5.Ulangi langkah [3] dan [4] hingga data siswa dari sekolah yang diperoleh dari langkah [1] seluruhnya berhasil dilakukan.
6.Ulangi langkah [1] hingga [5] untuk jenjang sekolah yang lain, jika langkah [1] dipecah berdasarkan jenjang (disarankan).
Jika mekanisme di atas dilakukan secara rapi dan tercatat, maka apabila terjadi sesuatu hal yang mengganggu proses sinkronisasi, maka tidak perlu dilakukan sinkronisasi ulang terhadap seluruh data, melainkan cukup diulang dari sejak gangguan terjadi. Hal ini memberi keuntungan baik pada sistem Dapodik maupun terhadap sistem lokal yaitu lebih hemat resource terutama penghematan waktu, tenaga mesin, dan bandwidth.
E. Penutup
Untuk bisa memanfaatkan layanan ini, akses harus dilakukan menggunakan akun Dapodik yang telah terdaftar dan aktif. Akun login Dapodik bisa diperoleh dengan mengirimkan surat permintaan operator baru, secara resmi dari Dinas Pendidikan Kota/Kab setempat ke Admin Dapodik Pusat. Perlu pula ditegaskan dalam surat permintaan tersebut bahwa akun yang diminta akan digunakan untuk proses otomasi (berdasarkan API Dapodik) atau untuk proses manual (sebagai operator entri). Tidak disarankan untuk berbagi akun antara tujuan akses API dengan sbg operator entri data.
A. UmumUntuk tujuan integrasi dengan sistem eksternal, sistem Dapodik menyediakan layanan komunikasi dengan memanfaatkan web service API (Application Programming Interface). Dengan memanfaatkan layanan komunikasi ini, sistem lain bisa memanfaatkan data-data yang tersedia dalam Dapodik untuk kepentingannya masing-masing. Walaupun demikian, mengingat Dapodik masih dalam tahap pengumpulan dan verifikasi data, untuk sementara layanan ini hanya bersifat searah dan read-only (baca saja). Ke depan, layanan komunikasi ini akan terus dikembangkan dengan menambah fitur modifikasi (insert, delete, update) dan format komunikasi yang lebih beragam (XML, JSON, dan lain sebagainya).
B. Spesifikasi Komunikasi
1. Komunikasi
Protocol HTTP (Hyper Text Transfer Protocol)
Method GET
Hostname operator.dapodik.org
Port 80
Path /dapodik/api.php
2. Pengenalan Pengguna
Layanan ini membutuhkan satu parameter masukan yang harus berisi nilai benar dan valid, untuk kepentingan otentikasi pengguna layanan. Input yang diharapkan bernama passport yang harus selalu disertakan setiap kali akan mengakses layanan Dapodik API (mandatory request parameter). Nilai passport yang benar dan harus digunakan dalam request-request API selanjutnya diperoleh dari proses login dimana nilai tersebut hanya akan valid dan diakui selama sesi login pengguna yang bersangkutan masih aktif.
3. Document Output Format
Format yang disediakan ada 2 macam yaitu INI/CONF atau JSON. Macam format yang dihasilkan diatur melalui parameter format pada masing-masing request.
Masing-masing keluaran diperlihatkan pada bagian OUTPUT pada masing-masing layanan yang tersedia, dengan susunan format INI/CONF terlebih dahulu kemudian diikuti dengan format keluaran JSON.
Untuk format INI atau CONF adalah daftar pasangan nama dan nilai ("name=value" pair) dengan EOL di tiap pasangan sedang untuk JSON bisa mengacu pada laman berikut format JSON.
C. Layanan yang Tersedia
Jangan lupa menambahkan parameter input passport dalam setiap request! Penulisan Keterangan Pembacaan
diapit petik ganda nilai tetap atau konstanta, gunakan apa adanya tanpa tanda petik.
diapit kurung siku nilai masukan atau keluaran, berisi nilai yang benar dan sesuai.
diakhiri bintang nilai masukan opsional, bisa diisi, bisa diabaikan.
1. Login
INPUT:
data "login"
username
passport
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
passport=
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
Sesi login akan terus aktif selama masih ada aktifitas request dalam session id yang bersangkutan. Sesi akan secara otomatis menjadi non-aktif (auto logout) jika tidak ada aktifitas request hingga 30 menit setelah login yang terakhir.
2. Daftar Seluruh Propinsi di Indonesia
INPUT:
data "propinsi"
passport
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
... {"kode_propinsi":
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
3. Daftar Seluruh Kota/Kabupaten dalam Propinsi
INPUT:
data "kota"
passport
propinsi
kota*
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
... {"kode_kota":
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
4. Daftar Sekolah dalam Kota/Kabupaten
INPUT:
data "npsn"
passport
propinsi
kota
jenjang
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
... {"npsn":
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-propinsi Lingkup propinsi tidak diijinkan {"status": "error-propinsi"} Lingkup propinsi tidak diijinkan
status=error-kota Lingkup kota tidak diijinkan {"status": "error-kota"} Lingkup kota tidak diijinkan
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
Kode jenjang yang dikenali:
•1 : SD
•2 : SMP
•3 : SMA/SMK
•4 : Perguruan Tinggi
•9 : Lain-lain
5. Informasi Sekolah Berdasarkan NPSN
INPUT:
data "npsn"
passport
sekolah
propinsi
kota
jenjang*
status*
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
status=
jenjang=
propinsi=
kota=
alamat=
"status":
"jenjang":
"propinsi":
"kota":
"alamat":
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
Kode status yang dikenali:
•1 : Negeri
•2 : Swasta
•6 : Kejuruan negeri
•7 : Kejuruan swasta
•8 : Negeri di bawah Kementerian Agama
•9 : Swasta di bawah Kementerian Agama
6.a. Daftar Siswa dalam Sekolah
INPUT:
data "nisn"
passport
sekolah
lulus* < 0
1 > (opsional, default = 0, 0 = daftar siswa aktif, 1 = daftar siswa berstatus lulus)
rev* < 0
1 > (opsional, default = 0)
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
•rev = 0:
...
•rev = 0:
{"nisn": {"tgl_lahir":
•rev = 1:
...
•rev = 1:
{"nisn": {"tmp_lahir":
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
6.b. Detil Siswa
INPUT:
data "nisn"
passport
siswa
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
... {"nisn": {"nama":
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
7. Daftar Guru dalam Sekolah
INPUT:
data "nign"
passport
sekolah
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
... {"nign": {"tgl_lahir":
PESAN KESALAHAN:
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
status=error-sekolah Lingkup sekolah tidak diijinkan {"status": "error-sekolah"} Lingkup sekolah tidak diijinkan
status=logout Kesalahan isi dari parameter data {"status": "logout"} Kesalahan isi passport yang dikirim
8. Logout
INPUT:
data "logout"
passport
format* < ini
json> (opsional, default = ini)
OUTPUT:
INI JSON
status=logout {"status": "logout"}
PESAN KESALAHAN:
status=error-layanan Kesalahan isi dari parameter data
INI JSON
status=error-layanan Kesalahan isi dari parameter data {"status": "error-layanan"} Kesalahan isi dari parameter data
D. Sinkronisasi Data
Layanan API Dapodik sementara hanya menyediakan data secara spesifik dalam lingkup tertentu. Untuk melakukan sinkronisasi data dalam jumlah besar (bulk), harus dilakukan dengan mekanisme perulangan terhadap layanan-layanan yang telah disediakan. Misal, untuk melakukan sinkronisasi data siswa dalam satu kota/kabupaten, bisa dilakukan dalam urutan berikut:
1.Ambil daftar sekolah dalam kota/kabupaten yang dimaksud. Akan lebih baik jika proses ini dipecah sejumlah kode jenjang yang dikenali agar tidak terlalu membebani server Dapodik.
2.Lakukan sinkronisasi data sekolah di database lokal berdasarkan hasil kembalian dari langkah [1].
3.Ambil daftar siswa untuk setiap sekolah berdasarkan hasil kembalian dari langkah [1].
4.Lakukan sinkronisasi data siswa di database lokal berdasarkan hasil kembalian dari langkah [3].
5.Ulangi langkah [3] dan [4] hingga data siswa dari sekolah yang diperoleh dari langkah [1] seluruhnya berhasil dilakukan.
6.Ulangi langkah [1] hingga [5] untuk jenjang sekolah yang lain, jika langkah [1] dipecah berdasarkan jenjang (disarankan).
Jika mekanisme di atas dilakukan secara rapi dan tercatat, maka apabila terjadi sesuatu hal yang mengganggu proses sinkronisasi, maka tidak perlu dilakukan sinkronisasi ulang terhadap seluruh data, melainkan cukup diulang dari sejak gangguan terjadi. Hal ini memberi keuntungan baik pada sistem Dapodik maupun terhadap sistem lokal yaitu lebih hemat resource terutama penghematan waktu, tenaga mesin, dan bandwidth.
E. Penutup
Untuk bisa memanfaatkan layanan ini, akses harus dilakukan menggunakan akun Dapodik yang telah terdaftar dan aktif. Akun login Dapodik bisa diperoleh dengan mengirimkan surat permintaan operator baru, secara resmi dari Dinas Pendidikan Kota/Kab setempat ke Admin Dapodik Pusat. Perlu pula ditegaskan dalam surat permintaan tersebut bahwa akun yang diminta akan digunakan untuk proses otomasi (berdasarkan API Dapodik) atau untuk proses manual (sebagai operator entri). Tidak disarankan untuk berbagi akun antara tujuan akses API dengan sbg operator entri data.