Panduan Akses
Application Programming Interface
(API)
Kementerian Riset dan Teknologi / Badan Riset dan Inovasi Nasional
Oleh:
Tim Web Service Jaringan dan Sarana-Pusdatin
PUSAT DATA DAN INFORMASI
KEMENTERIAN RISET DAN TEKNOLOGI
BADAN RISET DAN INOVASI NASIONAL
2
DAFTAR ISI
DAFTAR ISI ... 2
DAFTAR GAMBAR ... 3
A. Pendahuluan ... 4
B. Cara Mendapatkan Hak Akses Layanan Web Service ... 4
C. Cara Mengaktivasi Access Token ... 6
D. Cara Memperbarui Access Token (Refresh) ... 9
E. Cara Mengakses Data Menggunakan Access Token... 11
F. Cara Pengembang Mendaftarkan Web Service ke API Gateway ... 13
3
DAFTAR GAMBAR
Gambar 1. Alur Permohonan Hak Akses Web Service ... 6
Gambar 2. Mekanisme Mendapatkan Access Token ... 7
Gambar 3. Mendapatkan Access Token Menggunakan Postman ... 8
Gambar 4. Access Token Dan Refresh Token Yang Dapat Digunakan... 9
Gambar 5. Cara Menggunakan Access Token ... 9
Gambar 6. Mekanisme Refresh Token ... 10
Gambar 7. Refresh Token Menggunakan Postman... 11
Gambar 8. Access Token dan Refresh Token yang Baru ... 11
Gambar 9. Cara Menggunakan Access Token yang Baru ... 11
Gambar 10. Menggunakan Access Token Untuk Request Data ... 12
Gambar 11. Contoh Data Hasil Request API ... 12
Gambar 12. Mekanisme Pendaftaran Web Service Ke Pusdatin Kemenristekbrin ... 13
4
A.
Pendahuluan
Kementerian Riset dan Teknologi / Badan Riset dan Inovasi Nasional saat ini telah memiliki infrastruktur Web Service untuk melayani proses pertukaran data. Kemenristekbrin memiliki Pangkalan Data Ilmu Pengetahuan dan Teknologi (IPTEK) dan juga aplikasi-aplikasi pendukung lainnya. Aplikasi-aplikasi pendukung ini yang dikelola oleh masing Satuan Kerja (SatKer) saling melakukan pertukaran data masing-masing. Selain itu juga aplikasi-aplikasi pendukung tersebut juga membutuhkan data dari Pangkalan Data IPTEK dan juga dapat berkontribusi data ke Pangkalan Data IPTEK.
Layanan Web Service ini dibangun dengan pendekatan Microservice Architecture
dengan membuat sebuah Application Programming Interface Gateway (API Gateway). Sistem atau aplikasi lainnya dapat mengakses data yang terdapat pada aplikasi-aplikasi tertentu yang telah di daftarkan di API Gateway dengan terlebih dahulu melakukan otentikasi menggunakan metode seperti Basic Auth, Token API Key, JSON Web Token, Oauth2 dan lainnya. Pada panduan ini akan dibahas bagaimana pengembang aplikasi agar dapat melakukan otentikasi dan mengakses API pada Ristekbrin.
B.
Cara Mendapatkan Hak Akses Layanan
Web Service
Sebelum mengakses API Ristekbrin, pengembang aplikasi perlu untuk mendapatkan Hak Aksesyang akan digunakan pada saat otentikasi. Hak Akses ini dapat diperoleh dari pihak pengelola API Gateway yaitu pihak Pusdatin Kemenristekbrin. Adapun langkah-langkahnya untuk mendapatkan Hak Akses tersebut adalah sebagai berikut:
1. Client sebagai pihak yang akan menggunakan data yang terdapat pada Web Service
milik Kemenristekbrin harus mengajukan pembuatan akun untuk mengakses Portal API sebelumnya kepada pihak Pusdatin Kemenristekbrin. Setelah akun tersebut diberikan client dapat mengakses Portal API milik Kemenristekbrin. Portal API tersebut dapat diakses dengan menggunakan URL https://portalapi.ristekbrin.go.id setelah itu masukkan Username dan Password yang telah diberikan sebelumnya.
5 2. Pada halaman Portal API milik Kemenristekbrin, client dapat melihat semua daftar ketersediaan data pada Kemenristekbrin yang dapat diakses oleh pihak lainnya melalui layanan Web Service ini. Selain itu juga pada portal ini diperlihatkan cara atau metode yang dapat digunakan untuk mengakses data tersebut.
3. Apabila data yang dibutuhkan oleh client terdapat pada daftar data tersebut maka client dapat mengajukan permohonan untuk penggunaan data tersebut dengan cara mengisi informasi yang terdapat pada formulir Permohonan Layanan Web Service
(Form 1 pada Lampiran) kemudian client menyerahkan formulir tersebut kepada pihak Pusdatin sebagai Administrator layanan Web Service Kemenristekbrin. 4. Setelah formulir tersebut diterima oleh pihak Pusdatin, formulir tersebut kemudian
diteruskan kepada pihak yang memiliki data tersebut untuk meminta persetujuan data tersebut digunakan oleh client.
5. Apabila pihak pemilik data menyetujui data yang dimilikinya dapat diakses oleh pihak client maka pihak Pusdatin akan mendapatkan balasan persetujuan dari pihak pemilik data untuk membuatkan akses kepada client agar dapat mengakses data yang dibutuhkannya tersebut.
6. Pusdatin Kemenristekbrin selanjutnya akan membuatkan akses kepada pihak client dengan berdasarkan informasi yang diberikan pihak client sesuai dengan isian pada formulir Permohonan layanan Web Service.
6 7. Akses yang telah dibuat oleh pihak Pusdatin Kemenristekbrin selanjutnya akan diberikan kepada pihak client sehingga dapat digunakan oleh pihak client untuk mengakses data yang dibutuhkannya.
C.
Cara Mengaktivasi
Access Token
Setelah mendapatkan Hak Akses dari Pusdatin Kemenristekbrin client harus melakukan aktivasi dari Hak Akses tersebut sehingga client mendapatkan Access Token dan Refresh Token. Access Token inilah yang harus digunakan oleh pihak client pada setiap request data yang dilakukannya ke API Gateway milik Pusdatin Kemenristekbrin sehingga data
7 yang dibutuhkan dapat diperoleh dan digunakan. Berikut ini adalah contoh informasi yang terdapat pada Hak Akses yang diberikan oleh pihak Pusdatin Kemenristekbrin kepada pihak client untuk melakukan Aktivasi sehingga diperoleh Access Token.
Label Value client_id gWXHVJzMBVW6TXrJvrMghtECN1Gt7cxx client_secret WHWGxUyRNgAjk0T438dXGz0duHZngiIR provision_key 77ZRSjQQ8CGL3Lpdy8EEM70hSQSngmq8 authenticated_userid Ujicoba grant_type password
Sedangkan untuk melakukan proses aktivasi Hak Akses sehingga mendapatkan Access Token dapat dilakukan dengan menggunakan cURL atau Postman, berikut adalah contoh untuk melakukan proses aktivasi tersebut:
1. Lakukan request POST ke https://api.ristekbrin.go.id:8443/{service}/oauth2/token
dengan detail request sebagai berikut: Request Header :
Content-Type: form-data Request Body :
client_id: {Client ID}
client_secret: {Client Secret}
8 provision_key: {Provision Key}
authenticated_userid: {Authenticated User ID} grant_type: password
Contoh menggunakan cURL:
curl -k -X POST https://api.ristekbrin.go.id:8443/ujicoba/oauth2/token
--data “client_id= gWXHVJzMBVW6TXrJvrMghtECN1Gt7cxx” --data “client_secret= WHWGxUyRNgAjk0T438dXGz0duHZngiIR” --data “provision_key=77ZRSjQQ8CGL3Lpdy8EEM70hSQSngmq8” --data “authenticated_userid=Ujicoba”
--data “grant_type=password” --data “scope=akses”
Contoh Menggunakan Postman:
Masukkan alamat URL pada kolom yang telah disediakan dan juga masukkan informasi tambahan yang dibutuhkan pada bagian yang sudah disediakan seperti pada gambar dibawah ini:
9 2. Setelah itu lakukan request dan tunggu proses responsenya. Apabila berhasil maka respon akan memberikan hasil berupa Access Token dan juga Request Token seperti yang ditunjukkan gambar di bawah ini:
3. Gunakan Access Token ini pada setiap request dengan menyertakan header seperti berikut:
Authorization: Bearer uCJWEAPmKjfFEjic4cOdiFH29o398IM5
D.
Cara Memperbarui
Access Token
(
Refresh
)
Access Token yang didapat memiliki waktu kadaluarsa dalam satuan detik. Jika sudah kadaluarsa maka Access Token ini harus diperbarui lagi menggunakan Refresh Token. Pada mekanisme ini Access Token yang lama akan diganti dengan Access Token yang baru. Langkah-langkah untuk mendapatkan Access Token yang baru dapat dilihat pada Gambar di bawah ini.
Gambar 4. Access Token Dan Refresh Token Yang Dapat Digunakan Gambar 5. Cara Menggunakan Access Token
10 Untuk memperbarui Access Token yang sudah kadaluarsa dapat dilakukan dengan langkah-langkah sebagai berikut
1. Buat request POST ke https://api.ristekbrin.go.id:8443/{service}/oauth2/token
dengan detail sebagai berikut Request Header :
Content-Type: form-data Request Body :
client_id: {Client ID}
client_secret: {Client Secret} refresh_token: {Refresh Token} grant_type: refresh_token Contoh Menggunakan cURL:
curl -k -X POST https://api.ristekbrin.go.id:8443/ujicoba/oauth2/token
--data “client_id= gWXHVJzMBVW6TXrJvrMghtECN1Gt7cxx” --data “client_secret= WHWGxUyRNgAjk0T438dXGz0duHZngiIR” --data “refresh_token=ElvA6pkvjxcYJAQ1JMy2crxEbfiH11aE” --data “grant_type=refresh_token”
11 Contoh Menggunakan Postman:
Masukkan alamat URL pada kolom yang telah disediakan dan juga masukkan informasi tambahan yang dibutuhkan pada bagian yang sudah disediakan seperti pada gambar dibawah ini:
2. Setelah itu lakukan request dan di dalam response anda akan mendapatkan Access Token dan Refresh Token yang baru sebagai berikut:
3. Selanjutnya gunakan Access Token ini di setiap request dengan menyertakannya pada header seperti berikut ini:
Authorization: Bearer KndUBebRtu0BthCW3EqFknh7Yt96nhsn
E.
Cara Mengakses Data Menggunakan
Access Token
Pada bagian ini akan dijelaskan langkah-langkah yang harus dilakukan client untuk mengakses API menggunakan Access Token yang sudah didapatkan sebelumnya. Endpoint API yang akan digunakan sebagai contoh disini adalah Data IPTEK Nasional untuk
Gambar 7. Refresh Token Menggunakan Postman Gambar 8. Access Token dan Refresh Token yang Baru
12 mendapatkan daftar media publikasi penelitian di Indonesia. Berikut ini adalah URL dari endpoint API-nya.
GET https://api.ristekbrin.go.id:8443/data-iptek/media-publikasi
Ikuti langkah-langkah berikut untuk mengakses API Data IPTEK Nasional.
1. Dapatkan Access Token dengan mengikuti langkah-langkah yang telah dijelaskan sebelumnya. Misalkan Access Token yang didapatkan yaitu
6bqAoLemn66yHVdP5Hf73Xvp4skk4zwI
2. Buat request GET di Postman ke URL tujuan seperti ilustrasi berikut. GET https://api.ristekbrin.go.id:8443/data-iptek/media-publikasi
Header :
Authorization : Bearer 6bqAoLemn66yHVdP5Hf73Xvp4skk4zwI Contoh:
3. Lakukan request dan perhatikan response dari API dalam format JSON sebagai berikut.
Gambar 10. Menggunakan Access Token Untuk Request Data
13
F.
Cara Pengembang Mendaftarkan Web Service ke API Gateway
Para pengembang layanan Web Service pada setiap aplikasi-aplikasi pendukung yang dikembangkan dan yang dikelola oleh masing-masing Satuan Kerja dapat mendaftarkan layanan Web Service yang mereka miliki kepada pihak Administrator API Gateway yang dalam hal ini adalah Pusdatin Kemenristekbrin sehingga data yang terdapat pada aplikasi-aplikasi pendukung mereka dapat digunakan oleh pihak lain secara flexibel dan lebih aman.
Untuk dapat mendaftarkan layanan Web Service mereka ke API Gateway yang dimiliki oleh pihak Pusdatin Kemenristekbrin ada beberapa persyaratan yang harus dipenuhi oleh pihak pengembang Web Service tersebut. Selain itu juga terdapat langkah-langkah yang harus dilalui oleh pihak pengembang layanan Web Service sehingga layanan Web Service mereka terdaftar dan dapat digunakan oleh pihak lainnya melalui API Gateway Pusdatin Kemenristekbrin. Adapun persyaratan dan langkah tersebut dijelaskan pada gambar di bawah ini:
1. Pihak Satuan Kerja di Kemenristekbrin yang telah mengembangkan layanan Web Service pada aplikasi-aplikasi mereka dapat mengajukan pendaftaran layanan Web Service mereka ke Pusdatin Kemenristekbrin. Untuk proses pendaftaraan layanan Web Service pihak Satuan Kerja harus mengajukan permohonan ke pihak Pusdatin
14 dengan menyertakan formulir registrasi Web Service yang telah diisi sebelumnya (Form 2 pada Lampiran). Pada formulir tersebut terdapat informasi seperti alamat server Web Service yang dimiliki, URL layanan Web Service tersebut yang dapat diakses, informasi mengenai data yang tersedia dan dapat di akses pada layanan Web Service tersebut serta metode-metode yang dapat digunakan untuk mengakses data tersebut dan informasi-informasi penting lainnya yang harus dilengkapi. 2. Setelah pihak Administrator yang dalam hal ini adalah Pusdatin Kemenristekbrin
menerima formulir pendaftaran tersebut, maka selanjutnya pihak administrator akan mendaftarkan layanan Web Service tersebut pada API Gateway yang dimiliki Pusdatin sehingga layanan Web Service tersebut dapat digunakan oleh pihak-pihak yang lainnya. Selain itu juga administrator akan mendaftarkan infromasi-informasi penting seputar Web Service tersebut pada halaman API Portal Kemenristekbrin sebagai bahan dokumentasi dan juga infromasi ketersediaan data yang dapat dilihat oleh pihak yang ingin mengajukan permohonan penggunaan data ke Pusdatin Kemenristekbrin.
3. Setelah selesai pihak Pusdatin akan memberitahukan kepada pemilik layanan Web Service bahwa layanan mereka telah terdaftar dan dapat digunakan oleh berbagai pihak.
4. Pihak pemilik data dapat mengecek sendiri apakah layanan mereka telah terdaftar dan dapat digunakan atau tidak.
//GAMBAR
15
FORM 1
KOP SURAT
Nomor : Tanggal Lampiran : 1 Dokumen
Perihal : Permohonan Penggunaan Data Melalui Layanan Web Service Kemenristek/BRIN
Kepada Yth.
Kepala Pusat Data dan Infromasi
Kementerian Riset dan Teknologi / Badan Riset dan Inovasi Nasional
Dalam rangka meningkatkan kualitas layanan yang transparan, cepat, efektif, efisien, dan aman di lingkungan (Unit Kerja Pemohon) maka kami membutuhkan bantuan ketersediaan data yang terdapat pada layanan Web Service milik pihak Pusat Data dan Infromasi Kementeri Riset dan Teknologi / Badan Riset dan Inovasi Nasional. Data tersebut selanjutnya akan kami gunakan sebagai informasi yang akan diolah pada layanan yang dimiliki oleh instansi kami. Sehubungan dengan hal tersebut, kami mengajukan permohonan penggunaan data milik Kementerian Riset dan Teknologi / Badan Riset dan Inovasi Nasional melalui layanan Web Service sesuai dengan data terlampir yang telah kami sertakan. Untuk konfirmasi lebih lanjut melalui Saudara/Saudari (Nama PIC/Admin), Nomor Handphone atau pos elektronik: Alamat Pos Elektronik.
Demikian permohonan kami, atas perhatian dan kerjasamanya kami ucapkan terima kasih.
Pimpinan Satuan Kerja
Nama NIP
18 FORMULIR PERMOHONAN LAYANAN WEB SERVICE
A. Data Instansi Pemohon Nama Instansi Alamat Kota Kode Pos Telepon Alamat Email B. Data Pemohon Nama PIC Alamat Kota Kode Pos Telepon Alamat Email
C. Data Teknis Permohonan Layanan Web Service 1. Data Pada Web Service yang Dibutuhkan
... ... ... ...
19 2. Tujuan Permohonan Data
... ... ... ...
3. Spesifikasi Teknis Server Pemohon Yang Akan Mengakses Data
Nama Aplikasi Fungsi Aplikasi Alamat Domain IP Publik Aplikasi
Jakarta, ……… 2020 Pejabat Instansi,
Nama Pejabat NIP
FORM 2
KOP SURAT
Nomor : Tanggal Lampiran : 1 Dokumen
Perihal : Permohonan Pendaftaran Layanan Web Service ke Kemenristek/BRIN Kepada Yth.
Kepala Pusat Data dan Infromasi
Kementerian Riset dan Teknologi / Badan Riset dan Inovasi Nasional
Dalam rangka mewujudkan tata kelola pemerintah yang transparan, cepat, efektif, efisien, dan aman serta untuk penyeragaman data di lingkungan Kementerian Riset dan Teknologi / Badan Riset dan Inovasi Nasional maka dengan ini pihak (Unit Kerja Pihak Pendaftar) mengajukan pendaftaran data yang dapat diakses melalui API yang telah dikembangkan sebelumnya ke layanan Web Service milik Pihak Pusat Data dan Informasi Kementerian Riset dan Teknologi / Badan Riset dan Inovasi Nasional sehingga data tersebut dapat digunakan oleh pihak yang membutuhkan. Sehubungan dengan hal tersebut, kami mengajukan permohonan pendaftaran data milik Satuan Kerja kami ke layanan Web Service milik Pusdatin Kementerian Riset dan Teknologi / Badan Riset dan Inovasi Nasional sesuai dengan spesifikasi data terlampir.
Untuk konfirmasi lebih lanjut melalui Saudara/Saudari (Nama PIC/Admin), Nomor Handphone atau pos elektronik: Alamat Pos Elektronik.
Demikian permohonan kami, atas perhatian dan kerjasamanya kami ucapkan terima kasih.
Pimpinan Satuan Kerja
Nama NIP
21 FORMULIR PENDAFTARAN DATA KE LAYANAN WEB SERVICE
A. Data Instansi Pendaftar Nama Instansi Satuan Kerja Subbidang Alamat Kota Kode Pos Telepon Alamat Email B. Data Pengelola Nama Instansi Nama Pengelola Satuan Kerja Subbidang Jabatan Alamat Kota Kode Pos Telepon Alamat Email
22 C. Spesifikasi Teknis Data Yang akan Didaftarkan pada Layanan Web Service
IP Address Server Data : URL Lengkap Server Data : Port Server Data :
Endpoint Metode Akses Payload Deskripsi
Jakarta, ……… 2020 Pejabat Instansi,
Nama Pejabat NIP
