Konsep dasar membangun REST API

0
519
konsep dasar membangun rest api

Dari banyak inspirasi menulis untuk membuka artikel pertama pada blog ini, Saya memilih untuk menulis yang lebih konseptual. Pada kesempatan ini Kita hanya akan belajar konsep membangun REST API yang baik.

REST API tidak terdengar asing lagi di telinga para Programer, mungkin yang baru memulai dunia pemograman masih bingung apa itu REST API, sering mereka bertanya di forum-forum seperti ini.

Bagaimana cara mengakses database MySQL dari aplikasi Android?

Nah untuk membaca data yang ada di database seperti MySQL, kita membutuhkan sebuah web service, biasanya disebut dengan REST API. Kita akan membuat sebuah layanan (service) agar sebuah aplikasi bisa melakukan CRUD (Create, Read, Update, Delete) pada database.

Disini saya tidak membahas bahasa pemograman apa yang akan dipakai untuk membuat sebuah REST API, melainkan bagaimana konsep membangunnya. Ada beberapa poin penting yang saya kutip dari artikel dari luar sana dan saya sangat setuju dengan apa yang disebutkan di dalam artikel tersebut.

Beberapa konsep yang harus di terapkan saat membangun REST API.

1. Menggunakan Noun bukan Verbs

Pada poin pertama ini sama seperti yang Saya baca pada artikel tersebut, kita harus menggunakan kata benda (noun) dan jangan menggunakan kata kerja (verbs) dalam membuat REST API.

Misalkan saja kita ingin membuat REST API untuk mengakses dan mengubah article, mengakses dan mengubah berarti kita bisa melakukan CRUD pada services tersebut dengan memanfaatkan beberapa method umum dipakai seperti GET, POST, PUT dan DELETE, fungsi dari tiap method sudah di wakilkan oleh arti tiap kata.

Route GET POST PUT DELETE
/articles Menampilkan seluruh artikel Membuat artikel baru Mengubah beberapa artikel Menghapus semua artikel
/articles/12 Menampilkan detail arti Mengubah spesifik artikel Menghapus spesifik artikel

Seperti yang saya sebutkan, jangan menggunakan kata kerja, gunakanlah kata benda untuk mewakilkan REST API kalian, jangan lakukan seperti dibawah ini.

  • /createArticle
  • /deleteArticle
  • /article/create
  • /article/12/edit
  • dan lain-lain

Berikut salah satu contoh implementasi pada salah satu Micro Framework yaitu Lumen, disini terlihat pada pendefenisian routes untuk mengakses REST API Saya menggunakan method GET, POST, PUT dan DELETE, sebaiknya kalian bisa menggunakan konsep yang pertama ini.

Menggunakan Noun bukan Verbs pada Route

2. Jangan menggunakan GET untuk mengubah sesuatu

Seperti namanya, method GET hanya kita gunakan untuk mengambil data, entah itu satu, beberapa (hasil filter) atau seluruhnya (jangan lupa gunakan pagination).

Jika kalian ingin mengubah sesuatu entah itu menghapus, mengubah, menambah sebuah entry data, kalian bisa menggunakan POST, PUT dan DELETE sesuaikan dengan apa yang ingin Kalian lakukan.

Ingat! Jangan gunakan method GET untuk mengubah sesuatu.

3. Menggunakan kata Plural Nouns

Lagi-lagi pemilihan kata yang jadi pembahasan di poin ketiga, pada poin pertama kita harus memilih kata benda dan pada poin yang ketiga ini, kita diharuskan memilih kata benda yang jamak. Nah, disini lah saya akan sedikit menyampaikan beberapa isi hati kepada kalian yang masih sering membuat REST API dengan kata bahasa indonesia, karena tidak mungkin kan kalian akan menuliskan /artikel-artikel atau /artikel2 untuk REST API kalian, coba perhatikan baik-baik dan renungkan, apa terlihat sedikit buruk rupa?

Apa salahnya kalian mencoba menuliskan dalam bahasa inggris sekalian menambah vocabulary kalian. Jika kalian menggunakan bahasa inggris untuk membuat REST API, poin ketiga ini pasti terasa menguatkan konsep pada poin pertama.

Coba perhatikan

Route Keterangan
/user Jangan gunakan yang seperti ini, karena jika kalian melakukan GET all data, pasti terasa aneh membacanya
/users Sebaiknya membuat kata jamak dari users karena bila kita ingin melakukan spesifik action dengan REST API kita hanya menambahkannya pada path setelahnya pada url route tersebut. Contohnya
PUT /users/10

4. Menyediakan Filtering, Sorting dan Paging

Pada sebuah method GET kita bisa mengambil data dari REST API yang kita akses, misalnya saya mengakses REST API /articles, nah kalau saya mengakses tanpa parameter seperti itu backend harus menampilkan seluruh artikel yang saya punya didalam database, tapi kita pasti punya kendala nantinya, bagaimana kalau artikel kita terlalu banyak record datanya didalam database?

Disini lah kita diharuskan melakukan pagination pada REST API ber-method GET, biasanya melihat REST API yang memiliki parameter GET seperti /articles?page=1 dan bahkan kita bisa mengatur Limit seperti /articles?page=1&limit=5.

Pengurutan atau disebut Sorting, biasanya dilakukan untuk melakukan pengurutan berdasarkan id, tanggal, atau nama. Kalian bisa membuatnya dengan mendefenisikan seperti:

/articles?sort=desc&sortby=name. 

Keterangan:
sort merupakan parameter menentukan pengurutan mau Ascending (asc) atau Descending (des).
sortby
merupakan parameter menentukan field apa yang mau di urutkan.

Dan untuk yang terakhir adalah Filtering, filtering sendiri sangat sering digunakan untuk melakukan pencarian lebih spesifik di dalam sebuah kumpulan data. Misalkan saja

/articles?author_id=12&category_id=2

Maka REST API hanya menampilkan artikel yang di terbitkan oleh author ber-id 12 dan artikel tersebut memiliki kategori id 2, itu adalah salah satu contohnya.

Terakhir pada poin keempat ini, saya ingin mengingatkan kalian bahwa, Filtering, Sorting dan Paging bisa digabungkan menjadi satu dengan menambahkan symbol & setelah parameter sebelumnya.

5. Jangan lupa gunakan HTTP status codes

Nah ini yang sering banget saya perhatikan dari sekian banyak REST API, terkadang kita hanya dapat 3 jenis status codes saja.  404 – Not Found, 200 – Ok dan 500 – Internal Server Error.

Masih mending ada 3 jenis seperti itu, kadang cuma ada 2 doang, 200 – Ok  dan 500 – Internal Server Error (pertanda kodingan kamu banyak error).

Nah, sebaiknya kamu menggunakan beberapa status codes lainnya, seperti:

Code Status Message Keterangan
400 Bad Request digunakan bila REST API tidak mendapatkan parameter yang sesuai atau parameter required tidak terisi.
401 Unauthorized digunakan apabila REST API membutuhkan akses yang sesuai dengan levelnya, misalkan pengguna mau akses REST API yang tersedia hanya untuk administrator, jadi kita harus mengirimkan status code yang ini.
405 Method Not Allowed digunakan untuk memberitahu client, bahwa method ini tidak bisa di akses dengan cara yang dia lakukan. Misalnya ada REST API /login dan hanya tersedia untuk method POST saja, maka jika kita akses secara GET, DELETE ataupun PUT kita harus mengirimkan status code Method Not Allowed.

Makin banyak kalian menggunakan status code makin mudah dimengerti hasil response dari server ke client. Jika kalian tertarik untuk membaca lebih banyak tentang status code, kalian bisa langsung ke w3.org.

Ingat! Jangan pernah kirim status code 200 – Ok, padahal request tidak berhasil, entah itu Bad Request ataupun Unauthorized.

6. Gunakan lah struktur

Struktur yang dimaksudkan adalah mengstrukturkan hasil request kalian yang berbentuk JSON. sesuai format

 

Key Type Keterangan
success boolean property ini berisi status apakah request berhasil atau tidak. Misalkan saat membuat sebuah artikel baru, tapi lupa mengirim categori_id yang harusnya required, maka property ini akan di set false dan status code akan di set 400 – Bad Request
message String property ini berisi pesan yang akan muncul ketika request selesai di proses
data Object/Array of Object berikan data-data yang akan di berikan ke client, entah itu List of Articles, ataupun token dan lain-lain.

Berikut contoh struktur yang saya buat:

Gunakan lah struktur pada JSON

7. Gunakan token

Menggunakan token untuk memberi hak akses apakah sebuah REST API bisa di akses oleh client. Nah token bisa kalian hasilkan dari gabungan user_id, roles, timestamp dan jangan lupa pastikan token bisa di check apakah expired atau masih bisa digunakan.

Sekarang ini sudah ada sebuah tools untuk membantu kita men-generate token, JWT (JSON Web Token), kalian bisa membacanya lebih lanjut disini dan jangan lupa memberi status code 401 jika token sudah expired.

Dengan menggunakan token, backend bisa mengetahui pengguna mana yang sedang mengakses REST API tersebut dengan mengecek user_id dan roles yang tersisipkan ditoken.

Ingat! jangan gunakan session bahasa pemograman anda di REST API, karena tidak semua client bisa menghandle session, kecuali client kalian hanya berupa browser.

8. Sisipkan Token di Header

Jika kalian sudah menerapkan penggunaan token, maka sekarang saya ingin menyampaikan sisipkan lah token kalian di header. Masih banyak developer yang menyisipkan token melalui parameter di method GET.

Kenapa menaruh di header?

Saya memberikan sebuah percakapan disebuah diskusi membahas token harusnya di Header atau di Body/GET params

Pendapat penggunaan token pada header atau body

Salah satu komentator mengatakan “Prefer Header for better security (especially with used SSL)

Nah, mulai sekarang taruhlah token kalian dibagian header tinggalkan kebiasaan lama yang masih menaruh token di parameter GET.


Sekian saja, untuk artikel pertama kali ini. Maaf jika tidak semua poin yang ada pada artikel sebelah saya selipkan disini. Karena hanya beberapa saja yang memang penting untuk konsep di awal mula. Kalau seperti Versioning dan hal lainnya, kalian bisa merujuk ke sumber yang sudah saya selipkan dibagian bawah.

Terima kasih sudah berkunjung, artikel ini dibuat dengan emosi yang meledak-ledak karena ingin muntah melihat REST API yang dibuat dengan asal-asalan padahal sudah memakai sebuah Framework.