Memahami Dan Menggunakan REST API

Ada kemungkinan besar Anda menemukan istilah "REST API" jika Anda berpikir untuk mendapatkan data dari sumber lain di internet, seperti Twitter atau Github. Tapi apa itu REST API? Apa yang bisa dilakukannya untuk Anda? Bagaimana kamu menggunakannya?

Dalam artikel ini, Anda akan mempelajari semua yang perlu Anda ketahui tentang REST API agar dapat membaca dokumentasi API dan menggunakannya secara efektif.

Apa itu REST API?

Katakanlah Anda mencoba mencari video tentang Batman di Youtube. Anda membuka Youtube, ketik "Batman" ke dalam kolom pencarian, tekan enter, dan Anda melihat daftar video tentang Batman. REST API bekerja dengan cara yang serupa. Anda mencari sesuatu, dan Anda mendapatkan daftar hasil kembali dari layanan yang Anda minta.

API adalah antarmuka pemrograman aplikasi. Ini adalah seperangkat aturan yang memungkinkan program untuk berbicara satu sama lain. Pengembang membuat API di server dan mengizinkan klien untuk berbicara dengannya.

REST menentukan tampilan API. Itu singkatan dari "Transfer Negara Perwakilan". Ini adalah seperangkat aturan yang diikuti pengembang saat mereka membuat API mereka. Salah satu aturan ini menyatakan bahwa Anda harus bisa mendapatkan sepotong data (disebut sumber daya) saat Anda menautkan ke URL tertentu.

Setiap URL disebut permintaan sedangkan data yang dikirim kembali kepada Anda disebut tanggapan .

Anatomi Permintaan

Penting untuk diketahui bahwa permintaan terdiri dari empat hal:

1. Titik akhir
2. Metode
3. Header
4. Data (atau badan)

Titik akhir (atau rute) adalah url yang Anda minta. Ini mengikuti struktur ini:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

Root-endpoint adalah titik awal dari API yang Anda minta. Root-endpoint API Github adalah https://api.github.com sedangkan root-endpoint API Twitter adalah https://api.twitter.com .

Jalur menentukan sumber daya yang Anda minta. Anggap saja seperti mesin penjawab otomatis yang meminta Anda untuk menekan 1 untuk layanan, tekan 2 untuk layanan lain, 3 untuk layanan lain dan seterusnya.

Anda dapat mengakses jalur seperti halnya Anda dapat menautkan ke bagian situs web. Misalnya, untuk mendapatkan daftar semua posting yang ditandai di bawah "JavaScript" di Majalah Smashing, Anda menavigasi ke https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ adalah root-endpoint dan /tag/javascript adalah pathnya.

Untuk memahami jalur apa yang tersedia untuk Anda, Anda perlu melihat dokumentasi API. Misalnya, Anda ingin mendapatkan daftar repositori oleh pengguna tertentu melalui API Github. Dokumen memberitahu Anda untuk menggunakan jalur berikut untuk melakukannya:

 /users/:username/repos

Setiap titik dua ( : ) di jalur menunjukkan variabel. Anda harus mengganti nilai ini dengan nilai aktual saat Anda mengirim permintaan. Dalam hal ini, Anda harus mengganti :username dengan nama pengguna yang sebenarnya dari pengguna yang Anda cari. Jika saya mencari akun Github saya, saya akan mengganti :username dengan zellwk .

Titik akhir untuk mendapatkan daftar repo saya di Github adalah ini:

 https://api.github.com/users/zellwk/repos

Bagian terakhir dari titik akhir adalah parameter kueri . Secara teknis, parameter kueri bukan bagian dari arsitektur REST, tetapi Anda akan melihat banyak API menggunakannya. Jadi, untuk membantu Anda sepenuhnya memahami cara membaca dan menggunakan API, kami juga akan membicarakannya. Parameter kueri memberi Anda opsi untuk mengubah permintaan Anda dengan pasangan nilai kunci. Mereka selalu dimulai dengan tanda tanya ( ? ). Setiap pasangan parameter kemudian dipisahkan dengan ampersand ( & ), seperti ini:

 ?query1=value1&query2=value2

Saat Anda mencoba mendapatkan daftar repositori pengguna di Github, Anda menambahkan tiga parameter yang mungkin ke permintaan Anda untuk mengubah hasil yang diberikan kepada Anda:

Jika Anda ingin mendapatkan daftar repositori yang saya dorong baru-baru ini, Anda dapat mengatur sort ke push .

 https://api.github.com/users/zellwk/repos?sort=pushed

Bagaimana Anda tahu jika titik akhir ini berfungsi? Nah, saatnya untuk mencobanya!

Menguji Titik Akhir Dengan curl

Anda dapat mengirim permintaan dengan bahasa pemrograman apa pun. Pengguna JavaScript dapat menggunakan metode seperti Fetch API dan metode Ajax jQuery; Pengguna Ruby dapat menggunakan kelas Net::HTTP Ruby, pengguna Python dapat menggunakan Permintaan Python; dan seterusnya.

Untuk artikel ini, kita akan menggunakan utilitas baris perintah yang disebut cURL. Kami menggunakan cURL karena dokumentasi API biasanya ditulis dengan mengacu pada cURL. Jika Anda memahami cara menggunakan cURL, Anda tidak akan kesulitan memahami dokumentasi API. Kemudian, Anda dapat dengan mudah melakukan permintaan dengan bahasa pilihan Anda.

Sebelum melanjutkan, Anda harus memastikan bahwa Anda telah menginstal cURL di mesin Anda. Buka Terminal Anda dan ketik curl -version . Perintah ini memeriksa versi cURL yang telah Anda instal di sistem Anda.

 curl --version

Jika Anda tidak menginstal cURL, Anda akan mendapatkan kesalahan "perintah tidak ditemukan". Jika Anda mendapatkan kesalahan ini, Anda harus menginstal curl sebelum melanjutkan.

Untuk menggunakan cURL, Anda mengetik curl , diikuti dengan titik akhir yang Anda minta. Misalnya, untuk mendapatkan titik akhir root Github, Anda mengetik yang berikut:

 curl https://api.github.com

Setelah Anda menekan enter, Anda akan mendapatkan respons dari Github yang terlihat seperti ini:

Untuk mendapatkan daftar repositori pengguna, Anda memodifikasi titik akhir ke jalur yang benar, seperti yang telah kita bahas di atas. Untuk mendapatkan daftar repositori saya, Anda dapat menggunakan perintah ini:

 curl https://api.github.com/users/zellwk/repos

Jika Anda ingin menyertakan parameter kueri dengan cURL, pastikan Anda menambahkan garis miring terbalik ( \ ) sebelum ? dan = karakter. Ini karena ? dan = adalah karakter khusus di baris perintah. Anda perlu menggunakan \ sebelum mereka untuk baris perintah untuk menafsirkannya sebagai karakter normal:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

Coba gunakan salah satu perintah dan lakukan permintaan! Anda akan mendapatkan respons serupa dengan apa yang Anda lihat dengan root-endpont Github (tetapi dengan lebih banyak data).

JSON

JSON (JavaScript Object Notation) format umum untuk mengirim dan meminta data melalui REST API. Respons yang dikirim kembali oleh Github kepada Anda juga diformat sebagai JSON.

Objek JSON terlihat seperti Objek JavaScript. Di JSON, setiap properti dan nilai harus dibungkus dengan tanda kutip ganda, seperti ini:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

Kembali ke Anatomi Permintaan

Anda telah mempelajari bahwa permintaan terdiri dari empat bagian.

1. Titik akhir
2. Metode
3. Header
4. Data (atau badan)

Mari kita lihat apa yang membuat permintaan.

Metode

Metode adalah jenis permintaan yang Anda kirim ke server. Anda dapat memilih dari lima jenis di bawah ini:

• GET
• POST
• PUT
• PATCH
• DELETE

Metode ini memberikan arti untuk permintaan yang Anda buat. Mereka digunakan untuk melakukan empat kemungkinan tindakan: Create , Read , Update dan Delete (CRUD).

API memungkinkan Anda mengetahui metode permintaan apa yang digunakan untuk setiap permintaan. Misalnya, untuk mendapatkan daftar repositori pengguna, Anda memerlukan permintaan GET :

Permintaan GET diperlukan untuk mendapatkan daftar repositori dari pengguna. Untuk membuat repositori Github baru, Anda memerlukan permintaan POST :

Anda dapat mengatur metode permintaan di cURL dengan menulis -X atau --request , diikuti dengan metode permintaan. Perintah di bawah ini mencoba membuat repositori melalui cURL:

 curl -X POST https://api.github.com/user/repos

Coba jalankan permintaan ini. Anda akan mendapatkan respons yang memberi tahu Anda bahwa otentikasi diperlukan. (Lebih lanjut tentang otentikasi nanti).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Header

Header digunakan untuk memberikan informasi kepada klien dan server. Ini dapat digunakan untuk berbagai tujuan, seperti otentikasi dan memberikan informasi tentang konten isi. Anda dapat menemukan daftar header yang valid di Referensi Header HTTP MDN.

Header HTTP adalah pasangan nilai properti yang dipisahkan oleh titik dua. Contoh di bawah ini menunjukkan header yang memberi tahu server untuk mengharapkan konten JSON.

 "Content-Type: application/json". Missing the opening ".

Anda dapat mengirim header HTTP dengan curl melalui opsi -H atau --header . Untuk mengirim header di atas ke API Github, Anda menggunakan perintah ini:

 curl -H "Content-Type: application/json" https://api.github.com

(Catatan: header Content-Type bukan persyaratan API Github untuk bekerja. Ini hanya contoh untuk mengilustrasikan cara menggunakan header dengan cURL).

Untuk melihat header yang telah Anda kirim, Anda dapat menggunakan opsi -v atau --verbose saat Anda mengirim permintaan, seperti ini:

 curl -H "Content-Type: application/json" https://api.github.com -v 

Di sini, * mengacu pada informasi tambahan yang disediakan oleh cURL. > mengacu pada header permintaan, dan < mengacu pada header respons.

Data (Atau “Tubuh”)

Data (terkadang disebut “body” atau “message”) berisi informasi yang ingin Anda kirimkan ke server. Opsi ini hanya digunakan dengan permintaan POST , PUT , PATCH atau DELETE .

Untuk mengirim data melalui cURL, Anda dapat menggunakan opsi -d atau --data :

 curl -X POST <URL> -d property1=value1

Untuk mengirim beberapa bidang data, Anda dapat membuat beberapa opsi -d :

 curl -X POST <URL> -d property1=value1 -d property2=value2

Jika masuk akal, Anda dapat memecah permintaan Anda menjadi beberapa baris \ agar lebih mudah dibaca:

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Jika Anda tahu cara menjalankan server, Anda dapat membuat API dan menguji data Anda sendiri. Jika Anda belum tahu, tetapi merasa cukup berani untuk mencoba, Anda bisa mengikuti artikel ini untuk belajar membuat server dengan Node, Express, dan MongoDB

Jika Anda tidak ingin menjalankan server Anda, Anda dapat pergi ke Requestbin.com ( gratis! ) dan klik "buat titik akhir". Anda akan diberikan URL yang dapat Anda gunakan untuk menguji permintaan, seperti https://requestb.in/1ix963n1 yang ditunjukkan pada gambar di bawah.

Pastikan Anda membuat nampan permintaan Anda sendiri jika Anda ingin menguji permintaan Anda. Tempat permintaan hanya tetap terbuka selama 48 jam setelah pembuatannya. Pada saat Anda membaca artikel ini, tempat sampah yang saya buat di atas akan lama hilang.

Sekarang, coba kirim beberapa data ke nampan permintaan Anda, lalu segarkan halaman web nampan Anda. Anda akan melihat beberapa data, seperti ini:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

Secara default, cURL mengirimkan data seolah-olah mereka dikirim melalui "bidang formulir" di halaman. Jika Anda ingin mengirim data JSON, Anda harus menyetel Content-Type ke application/json , dan Anda harus memformat data Anda sebagai objek JSON, seperti ini:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

Dan itu (hampir!) semua yang perlu Anda ketahui tentang struktur permintaan.

Sekarang, ingat ketika Anda mencoba mengirim permintaan POST melalui API Github, Anda mendapat pesan yang mengatakan "Memerlukan otentikasi"? Nah, itu karena Anda tidak berwenang untuk melakukan permintaan POST !

Autentikasi

Anda tidak akan mengizinkan siapa pun untuk mengakses rekening bank Anda tanpa izin Anda, bukan? Pada pemikiran yang sama, pengembang menerapkan langkah-langkah untuk memastikan Anda melakukan tindakan hanya jika Anda diizinkan untuk melakukannya. Ini mencegah orang lain meniru identitas Anda.

Sejak POST , PUT , PATCH dan DELETE permintaan mengubah database, pengembang hampir selalu menempatkan mereka di balik dinding otentikasi. Dalam beberapa kasus, permintaan GET juga memerlukan otentikasi (seperti ketika Anda mengakses rekening bank Anda untuk memeriksa saldo Anda saat ini, misalnya).

Di web, ada dua cara utama untuk mengautentikasi diri Anda:

1. Dengan nama pengguna dan kata sandi (juga disebut otentikasi dasar)
2. Dengan token rahasia

Metode token rahasia termasuk oAuth, yang memungkinkan Anda untuk mengotentikasi diri Anda dengan jaringan media sosial seperti Github, Google, Twitter, Facebook, dll.

Untuk artikel ini, Anda hanya akan belajar menggunakan otentikasi dasar dengan nama pengguna dan kata sandi. Jika Anda tertarik untuk mengautentikasi dengan oAuth, saya sarankan membaca "Apa yang Perlu Anda Ketahui Tentang OAuth2 Dan Masuk Dengan Facebook" oleh Zack Grossbart.

Untuk melakukan otentikasi dasar dengan cURL, Anda dapat menggunakan opsi -u , diikuti dengan nama pengguna dan kata sandi Anda, seperti ini:

 curl -x POST -u "username:password" https://api.github.com/user/repos

Coba autentikasi diri Anda dengan nama pengguna dan kata sandi Anda dalam permintaan di atas. Setelah Anda berhasil dalam otentikasi, Anda akan melihat perubahan respons dari "Memerlukan otentikasi" menjadi "Masalah parsing JSON."

Ini karena Anda belum memberikan data apa pun (yang diperlukan oleh semua permintaan POST , PUT , PATCH dan DELETE ) ke server.

Dengan pengetahuan yang telah Anda pelajari sejauh ini, Anda seharusnya dapat mengedit kode di atas untuk membuat repositori Github melalui cURL Anda. Saya akan meninggalkan Anda untuk mencobanya sendiri!

Sekarang, mari kita bicara tentang kode Status HTTP dan pesan kesalahan.

Kode Status HTTP Dan Pesan Kesalahan

Beberapa pesan yang Anda terima sebelumnya, seperti "Memerlukan otentikasi" dan "Masalah parsing JSON" adalah pesan kesalahan. Mereka hanya muncul ketika ada yang salah dengan permintaan Anda. Kode status HTTP memungkinkan Anda memberi tahu status respons dengan cepat. Kisaran dari 100+ hingga 500+. Secara umum, angka mengikuti aturan berikut:

1. 200+ berarti permintaan telah berhasil .
2. 300+ berarti permintaan dialihkan ke URL lain
3. 400+ berarti telah terjadi kesalahan yang berasal dari klien
4. 500+ berarti telah terjadi kesalahan yang berasal dari server

Anda dapat men-debug status respons dengan opsi verbose ( -v atau --verbose ) atau opsi head ( -I atau --head ).

Misalnya, jika Anda mencoba menambahkan -I ke permintaan POST tanpa memberikan nama pengguna dan kata sandi Anda, Anda akan mendapatkan kode status 401 (Tidak Diotorisasi):

Jika permintaan Anda tidak valid karena data Anda salah atau hilang, Anda biasanya mendapatkan kode status 400 (Permintaan Buruk).

Untuk mendapatkan informasi lebih lanjut tentang kode status HTTP tertentu, Anda mungkin ingin berkonsultasi dengan Referensi Status HTTP MDN.

Versi API

Pengembang memperbarui API mereka dari waktu ke waktu. Terkadang, API dapat berubah begitu banyak sehingga pengembang memutuskan untuk memutakhirkan API mereka ke versi lain. Jika ini terjadi, dan aplikasi Anda rusak, biasanya karena Anda telah menulis kode untuk API yang lebih lama, tetapi permintaan Anda mengarah ke API yang lebih baru.

Anda dapat meminta versi API tertentu dengan dua cara. Cara yang Anda pilih bergantung pada cara penulisan API.

Kedua cara tersebut adalah:

1. Langsung di titik akhir
2. Dalam tajuk permintaan

Twitter, misalnya, menggunakan cara pertama. Pada saat penulisan, API Twitter berada di versi 1.1, yang terbukti melalui titik akhirnya:

 https://api.twitter.com/1.1/account/settings.json

Github, di sisi lain, menggunakan metode kedua. Pada saat penulisan, API Github berada di versi 3, dan Anda dapat menentukan versi dengan header Accept :

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Membungkus

Dalam artikel ini, Anda mempelajari apa itu REST API dan bagaimana menggunakan cURL untuk melakukan permintaan dengan metode GET , POST , PUT , PATCH dan DELETE . Selain itu, Anda juga mempelajari cara mengautentikasi permintaan Anda dengan opsi -u , dan apa arti status HTTP.

Saya harap artikel ini cukup membantu Anda mempelajari REST API, dan Anda dapat menggunakannya dengan lancar saat membuat aplikasi. Jangan ragu untuk mampir ke blog saya atau tinggalkan komentar Anda di bawah jika Anda memiliki pertanyaan.