aulch’s — week 11
API DOCUMENTATION
Di minggu ini, saya mulai mencoba untuk membuat dokumentasi dari API yang merupakan salah satu produk yang akan kami hasilkan.
Sudah cukup banyak tools yang dapat digunakan untuk generate dokumentasi dari sebuah API, misalnya apiary.io. Namun pada projek ini, saya menggunakan apidocjs. apidocjs ini dapat digunakan untuk seluruh bahasa yang mendukung comment block loh!
Oh iya, ketika kita membuat sebuah dokumentasi untuk API, yang dihasilkan bukan hanya sehalaman teks yang menjelaskan parameter dan fungsi-fungsi yang digunakan, tapi merupakan sebuah halaman HTML beserta CSS-nya! Waah, sangat membantu meringankan pekerjaan kita bukan?!
CSS-nya juga diubah-ubah sesuai kebutuhan. Namun tentu saja butuh waktu yang cukup untuk melakukannya. Karena pada projek ini kebetulan CSS yang dihasilkan oleh halaman API tidak jauh berbeda dengan tema warna yang kami gunakan untuk website, maka kami memilih untuk tidak mengotak-atiknya.
Nah, awalnya saya bingung bagaimana cara generate API Documentation pada OS Windows (8.1) karena ketika googling ga nemu tutorial yang literally jelasin caranya. Akhirnya saya tanya Kevin Ega untuk mencari tahu langkah awalnya. Yap! karena apidocjs ini menggunakan node.js, maka langkah pertama saya pastinya
1. Menginstall node.js pada PC -bisa didapat dari web nodejs.org-
Ikuti saja langkah-langkah yang ada, cukup mudah kok!
selanjutnya, kita bermain dengan command prompt :) buka command prompt pada folder web (saya menggunakan framework laravel dan web untuk projek saya berada pada folder web) yang menyimpan apidoc.json yang akan kita generate.
Kita buka command prompt kemudian install npm pada PC,
2. Ketikkan npm install apidoc -g
hasil dari perintah di atas adalah sebuah folder Roaming/npm dan file apidoc di dalamnya C://Users/Aulia Chairunisa/AppData/Roaming/npm/apidoc.
sebelum kita generate dokumentasi dari API, kita harus menambahkan keterangan-keterangan yang akan dibaca oleh mesin generator sebagai pengisi field-field yang dibutuhkan. Untuk daftar parameter dengan penjelasan lengkap dapat dilihat di sini
ini contoh penggunaan di method yang digunakan untuk API kita yang disusun oleh Puti
Setelah itu kita generate dengan input file *.json yang bernama apidoc yang ada di dalam folder app pada web laravel kita.
3. Ketikkan apidoc -i app/ -o apidoc/
Isi dari file apidoc.json itu ialah
Jalankan perintah tersebut kemudian terdapat informasi bahwa folder apidoc yang berisi dokumentasi API telah selesai di-generate.
Berikut contoh dari API Documentation yang berhasil dibuat
selesai deh! Dokumentasi siap digunakan :)
Role Management
Berdasarkan penjabaran mengenai role management yang ada di https://msdn.microsoft.com/en-us/library/5k850zwb.aspx, pada produk kami, terdapat dua role, yaitu user/developer pengguna API dan program crawler kemudian admin yang mengelola web, program crawler, serta API itu sendiri.
Mengapa? di dalam web tersebut dijelaskan bahwa kita dapat membuat pengaturan akses ketika kita memiliki role-role tertentu. Misalnya halaman login hanya dapat diakses oleh admin, user biasa hanya dapat melihat halaman landing page, dokumentasi baik dari API maupun program crawler-nya, dsb. Hal-hal tersebut lah yang membuat produk kami ini memiliki role management.
Satu user dapat memiliki lebih dari satu peran, namun pada projek ini, user hanya dapat menjalankan sebuah peran, menjadi seorang admin atau user biasa (pengguna produk).
pembagian peran ini bertujuan untuk mempermudah kita dalam mengatur pengelolaan halaman kepada user. halaman mana saja yang harus dilihat oleh user biasa, mana yang hanya boleh admin saja. Jangan sampai halaman admin dapat diakses oleh user selain admin.
untuk memastikan bahwa yang mengakses halaman admin adalah orang yang tepat, maka kita dapat membuat “pengamanan” dengan menggunakan OAuth, misalnya. untuk memastikan bahwa yang memiliki akses untuk melihat halaman admin hanyalah admin.
Applying Suitable Algorithm and Data Structures
Dari website http://study.com/academy/lesson/what-is-an-algorithm-in-programming-definition-examples-analysis.html#transcriptHeader didapat definisi dari sebuah algoritma dalam pemrograman, yaitu seperti sebuah resep, ia memiliki langkah-langkah tepat dan sesuai yang dibutuhkan komputer untuk menyelesaikan sebuah masalah atau mencapai tujuannya. Dalam membuat sebuah program crawler, saya mendapatkan tugas untuk membuat sebua kelas yang dapat digunakan untuk insert data ke dalam database. Database yang digunakan oleh program kami ialah MongoDB.
Untuk insert to database, tentu ada prosedur yang harus dilakukan sebelum akhirnya kita memanggil method yang akan menambahkan data baru ke dalam database kita.
Dalam program ini, saya membuat sebuah objek DB, dimana objek ini nantinya akan digunakan untuk menghubungkan database yang kita gunakan beserta port dan juga nama dari database kita. Jika kita menggunakan database lokal, kita dapat menggunakan host: localhost dengan port: 27017 dan nama database sesuai dengan yang kita buat. dalam projek ini, kami menggunakan host: ds023520.mongolab.com, port: 23520, dan nama database: inspirecrawlerdb.
Kemudian kita hubungkan ke collection yang kita inginkan. Karena kita ingin insert into quote collection, maka kita hubungkan program kita dengan membuat objek DBCollection
Barulah kita buat sebuah objek yang berfungsi sebagai pointer kita untuk insert tiap data yang dibutuhkan. Gunakan metode put() untuk insert into collection.
Berikut kelas yang pertama kali saya buat untuk insert data into collection
Namun terdapat beberapa method atau sintaks yang sudah obsolete, sehingga sudah terdapat perubahan pada source code tersebut. untuk melihat perubahan tersebut, silakan cek github kami.
Kemudian berdasarkan definisi struktur data yang ada di web http://searchsqlserver.techtarget.com/definition/data-structure, kami memilih collection (pada MongoDB) sebagai cara untuk menyimpan data-data yang ada. Mengapa tidak berbentuk tabel seperti pada database biasanya? Karena data yang kami miliki bukanlah relasional dan hanya data dengan atribut-atribut sederhana. Sehingga akan lebih mudah dan cepat jika kita membutuhkan data-data tersebut.
Sekian pembelajaran saya mengenai API Documentation, Role Management, dan Applying Suitable Algorithm and Data Structures.
