Rute yang Baik versus Rute yang Buruk
Memberi nama API Anda dengan benar adalah langkah pertama dalam mendesain API yang baik. Ketika nama API mengikuti sebuah konvensi, maka nama tersebut memberikan banyak informasi tentang API dan tujuannya. Untuk membuat endpoint API yang bermakna, Anda perlu mengikuti beberapa panduan dan aturan sederhana.
Dalam bacaan ini, Anda akan belajar tentang konvensi penamaan API dan membiasakan diri Anda dengan titik akhir API yang baik vs titik akhir API yang buruk, atau rute yang baik dan buruk.
Aturan 01: Semuanya dalam huruf kecil, dengan tanda hubung dan tidak disingkat
URI API Anda harus selalu menggunakan huruf kecil. Jangan gunakan camelCase, PascalCase, atau Title case ketika Anda mendesain API. Selain itu, pisahkan beberapa kata dengan menggunakan tanda hubung, bukan garis bawah. Jangan menyimpan kata yang disingkat, atau dipendekkan, dalam URI Anda; selalu gunakan bentuk lengkap dan bermakna.
Jika API Anda menerima sebuah variabel, Anda harus selalu merepresentasikannya dalam camelCase, dan membungkusnya di dalam satu set kurung kurawal {}.
Mari kita lihat contoh berikut ini.
URI | Status | Mengapa |
|---|---|---|
/pelanggan | Baik | Jamak dan huruf kecil |
/pelanggan/16/nomor-telepon | Baik | Huruf kecil dan tanda hubung digunakan untuk memisahkan kata |
/pelanggan/16/alamat/rumah | Baik | Huruf kecil, tanpa garis miring, menampilkan hubungan hirarkis dengan garis miring ke depan. |
/pengguna/{userId} | Baik | Variabel dalam huruf besar-kecil, dan tidak ada tanda hubung pada nama variabel |
/Pelanggan | Buruk | Huruf besar/kecil |
/umumAnggota | Buruk | huruf besar/kecil, tanpa tanda hubung untuk memisahkan kata |
/MenuIsi/AnggotaUmum | Buruk | Huruf besar Pascal |
/pelanggan/16/tel-no | Buruk | Singkatan |
/pelanggan/16/nomor_telepon | Buruk | Garis bawah |
/pelanggan/16/nomor_telepon | Buruk | Tidak ada pemisahan kata |
/pengguna/{id-pengguna} | Buruk | Variabel harus menggunakan huruf besar-kecil, dan tanda hubung di antara kata |
Aturan 02: Gunakan garis miring ke depan untuk menunjukkan hubungan hierarki
Selalu gunakan garis miring ke depan dalam URI API Anda untuk menunjukkan hubungan hierarki. Untuk memahami aturan ini, pertimbangkan skenario berikut ini dan hubungan dari titik akhir API.
Sebuah toko dapat memiliki pelanggan yang telah melakukan banyak pesanan dan setiap pesanan ini dapat memiliki alamat pengiriman, item menu, dan tagihan.
URI | Status |
|---|---|
/store/pelanggan/{pelangganId}/pesanan | Baik |
/store/pesanan/{pesananId} | Baik |
/store/pesanan/{pesananId}/menu-item | Baik |
Demikian pula, sebuah perpustakaan dapat memiliki buku-buku dari banyak penulis. Setiap buku memiliki nomor ISBN.
URI | Status |
|---|---|
/perpustakaan/pengarang/buku | Baik |
/perpustakaan/buku/{id-buku}/isbn | Baik |
Aturan 03: Gunakan kata benda untuk nama sumber daya, bukan kata kerja
Salah satu fitur yang paling menonjol dari REST API adalah bahwa API ini menggunakan kata benda untuk mengindikasikan sumber daya, bukan kata kerja. Dan Anda harus selalu berpegang pada aturan ini ketika mendesain API Anda. Anda juga harus menggunakan kata benda jamak untuk menunjukkan koleksi.
URI | Diharapkan | Status | Mengapa |
|---|---|---|---|
/pesanan | Koleksi | Baik | Menggunakan kata benda, bukan kata kerja |
/pengguna/{userId} | Pengguna tunggal | Baik | Menggunakan kata benda dan hubungan hierarki yang tepat dan konvensi penamaan |
/order | Koleksi | Buruk | Menggunakan kata benda tunggal untuk sebuah koleksi |
/getOrder | Sumber daya tunggal | Buruk | Kata kerja, camelCase |
/getUser/{userId} | Pengguna tunggal | Buruk | Kata kerja, huruf besar/kecil |
Aturan 04: Hindari karakter khusus
Anda harus selalu menghindari karakter khusus di titik akhir API Anda. Karakter khusus dapat membingungkan dan secara teknis rumit bagi pengguna Anda. Pertimbangkan contoh-contoh buruk berikut ini.
URI | Status | Mengapa |
|---|---|---|
/pengguna/12|23|23/alamat | Buruk | Karakter khusus | |
/orders/16/menu^items | Buruk | Karakter khusus ^ |
Jika API Anda dapat menerima beberapa id pengguna, maka id pengguna tersebut harus dipisahkan dengan menggunakan koma, seperti yang ditunjukkan di bawah ini.
URI | Status | Mengapa |
|---|---|---|
/pengguna/12,23,23/alamat | Baik | Menggunakan koma untuk pemisahan |
Aturan 05: Hindari ekstensi berkas dalam URI
Anda harus selalu menghindari ekstensi berkas dalam nama API Anda. Sebagai contoh, jika API Anda dapat menghasilkan keluaran dalam format JSON dan XML, maka seharusnya tidak terlihat seperti ini.
URI | Status | Mengapa |
|---|---|---|
/sports/basketball/teams/{teamId}.json | Buruk | Ekstensi file pada akhirnya |
/sports/basketball/teams/{teamId}.xml | Buruk | Ekstensi file di bagian akhir |
Sebagai gantinya, klien Anda harus dapat menunjukkan format yang diharapkan dalam string kueri, seperti ini.
URI | Status | Mengapa |
|---|---|---|
/sports/basketball/teams/{teamId}?format=json | Baik | Tidak ada ekstensi file |
/sports/basketball/teams/{teamId}?format=xml | Baik | Tidak ada ekstensi file |
Demikian pula, jika API Anda menyajikan berkas statis, misalnya berkas CSS atau JavaScript, Anda harus menggunakan titik akhir seperti berikut ini untuk mengirimkan berkas sumber yang telah diperkecil dan asli. Anda juga dapat menggunakan string kueri untuk mendapatkan versi yang diperkecil atau versi asli. Beberapa pengembang API menggunakan format keluaran seperti ekstensi file di akhir titik akhir API biasa, yang juga merupakan praktik buruk.
URI | Status | Mengapa |
|---|---|---|
/assets/js/jquery/3.12/min | Baik | Tidak ada ekstensi file |
/assets/js/jquery/3.12/source | Baik | Tidak ada ekstensi file |
/assets/js/jquery/3.12/?format=min | Baik | Tidak ada ekstensi file |
/assets/js/jquery/3.12/?format=source | Baik | Tidak ada ekstensi file |
/menu-items?format=json | Baik | Titik akhir yang dinamai dengan sempurna dengan format keluaran yang diharapkan dalam string kueri |
/menu-items.json | Buruk | Menggunakan format keluaran yang diharapkan sebagai ekstensi file |
Aturan 06: Gunakan parameter kueri untuk memfilter jika diperlukan
Ketika mendesain API, Anda harus selalu melakukan pemfilteran data menggunakan string kueri. Hal ini sama ketika Anda mengharapkan beberapa parameter tambahan, seperti jumlah item per halaman dan nomor halaman.
Pertimbangkan contoh situs perjalanan ini. Anda ingin menemukan lokasi mana saja yang pernah dikunjungi oleh pengguna tertentu. Dan kemudian Anda ingin mengetahui lokasi mana saja di Amerika Serikat yang telah dikunjungi oleh pengguna tersebut.
URI | Status | Mengapa |
|---|---|---|
/pengguna/{userId}/lokasi | Bagus | Hierarkis |
/users/{userId}/locations?country=USA | Baik | camelCase, tidak ada pemisahan kata |
/artikel?per-halaman=10&halaman=2 | Baik | Penggunaan string kueri yang tepat |
/pengguna/{userId}/lokasi/USA | Buruk | Tidak menggunakan string kueri untuk memfilter data |
/artikel/halaman/2/item-per-halaman/10 | Buruk | Berlebihan dan tidak jelas |
Aturan 07: Tidak ada garis miring di belakang
Saat membagikan titik akhir API dengan orang lain dalam tim Anda, atau di depan umum, hindari penggunaan garis miring di akhir titik akhir API. Perhatikan contoh berikut ini
URI | Status | Mengapa |
|---|---|---|
/pengguna/{userId} | Baik | Tidak ada garis miring di belakang |
/artikel/{artikelId}/pengarang | Baik | Tidak ada garis miring di belakang |
/pengguna/{penggunaId}/ | Buruk | Garis miring |
/artikel/{artikelId}/pengarang/ | Buruk | Garis miring tertinggal |
Kesimpulan
Sekarang Anda telah memahami cara membuat endpoint REST API dengan nama yang baik. Ingat, strategi penamaan yang konsisten untuk API Anda adalah salah satu keputusan desain yang paling penting untuk keseluruhan proyek!
There are no comments for now.