5 Aturan Emas untuk Desain API Web yang Hebat

Pernah menemukan diri Anda bertanya-tanya "apa yang mereka pikirkan?" saat mengintegrasikan layanan web melalui API-nya? Jika tidak, Anda jauh lebih beruntung daripada saya.

Setiap pengembang perangkat lunak tahu betapa mudahnya membiarkan proyek berkembang menjadi kode spageti, dan API web tidak kurang rentan untuk menghasilkan web yang kusut. Tapi tidak perlu seperti itu. Sebenarnya, adalah mungkin untuk merancang API web hebat yang benar-benar akan dinikmati orang, dan Anda juga akan menikmati pembuatannya. Tapi bagaimana caranya? Jawaban atas pertanyaan itu adalah tentang apa posting ini.

Perspektif

Sebagian besar waktu ketika Anda sedang membangun solusi, Anda sedang merancang untuk pengguna akhir yang bukan programmer, atau yang umumnya tidak canggih secara teknis. Anda memberi mereka antarmuka grafis dan, jika Anda telah melakukan pekerjaan Anda dengan benar, Anda telah memperoleh ide yang cukup bagus dari mereka tentang apa yang mereka perlukan untuk dilakukan antarmuka.

Tetapi pengembangan API berbeda. Anda mendesain antarmuka untuk programmer , mungkin tanpa mengetahui siapa mereka. Dan siapa pun mereka, mereka akan memiliki kecanggihan teknis (atau setidaknya akan berpikir bahwa mereka memiliki kecanggihan teknis) untuk menunjukkan setiap kekurangan kecil dalam perangkat lunak Anda. Pengguna Anda kemungkinan akan sama kritisnya dengan API Anda seperti halnya Anda terhadap mereka, dan akan sangat senang mengkritisinya.

Dan di situlah letak ironi, omong-omong. Jika ada yang harus memahami cara membuat API web yang mudah digunakan, itu adalah Anda . Lagi pula, Anda adalah seorang insinyur perangkat lunak sama seperti pengguna API Anda, jadi Anda berbagi perspektif mereka. bukan?

Nah, sementara Anda tentu memahami perspektif mereka, Anda tidak harus berbagi perspektif mereka. Saat Anda mengembangkan atau meningkatkan API, Anda memiliki perspektif desainer API sedangkan mereka memiliki perspektif pengguna API .

Desainer API biasanya berfokus pada pertanyaan seperti “Apa yang perlu dilakukan layanan ini?” atau “Apa yang perlu disediakan oleh layanan ini?” , sementara pengguna API berfokus pada "Bagaimana cara menggunakan API ini untuk melakukan apa yang saya butuhkan?" , atau lebih tepatnya, “Bagaimana saya bisa mengeluarkan upaya minimal untuk mendapatkan apa yang saya butuhkan dari API ini?” .

Pertanyaan-pertanyaan yang berbeda ini mengarah pada dua perspektif yang sangat berbeda. Akibatnya, prasyarat yang diperlukan untuk mendesain API yang hebat adalah mengubah perspektif Anda dari desainer API ke perspektif pengguna API. Dengan kata lain, teruslah bertanya pada diri sendiri pertanyaan yang secara alami akan Anda tanyakan jika Anda adalah pengguna Anda sendiri. Daripada memikirkan tentang apa yang dapat dilakukan API Anda, pikirkan tentang berbagai cara yang mungkin diperlukan atau ingin digunakan , lalu fokuslah untuk membuat tugas-tugas tersebut semudah mungkin bagi pengguna API Anda.

Meskipun ini mungkin terdengar mudah dan jelas, namun mengejutkan betapa jarangnya API yang dirancang dengan cara ini. Pikirkan tentang API yang Anda temui dalam karier Anda. Seberapa sering mereka tampaknya telah dirancang dengan perspektif ini dalam pikiran? Desain API Web bisa jadi menantang.

Jadi dengan itu, mari kita lanjutkan dan bicarakan tentang 5 Aturan Emas untuk Mendesain Web API yang Hebat , yaitu:

1. Dokumentasi
2. Stabilitas dan Konsistensi
3. Fleksibilitas
4. Keamanan
5. Kemudahan Adopsi

Aturan 1: Dokumentasi

Dokumentasi. Ya, saya mulai dari sini.

Apakah Anda membenci dokumentasi? Yah, saya bisa berempati, tetapi kenakan topi "perspektif pengguna" Anda dan saya berani bertaruh bahwa satu hal yang lebih Anda benci daripada harus menulis dokumentasi adalah harus mencoba menggunakan API yang tidak berdokumen. Saya mengistirahatkan kasus saya.

Intinya adalah, jika Anda ingin siapa pun menggunakan API Anda, dokumentasi sangat penting. Anda hanya perlu melakukan ini dengan benar. Ini adalah hal pertama yang akan dilihat pengguna, jadi dalam beberapa hal ini seperti bungkus kado. Hadir dengan baik, dan orang-orang lebih cenderung menggunakan API Anda dan tahan dengan keistimewaan apa pun.

Jadi bagaimana kita menulis dokumentasi yang baik?

Bagian yang relatif mudah adalah mendokumentasikan metode API itu sendiri; yaitu, contoh permintaan dan tanggapan, beserta deskripsi masing-masing elemen di keduanya. Untungnya, ada semakin banyak perangkat lunak yang memfasilitasi dan menyederhanakan tugas menghasilkan dokumentasi. Atau Anda dapat menulis sendiri sesuatu yang mengintrospeksi API, titik akhir, dan fungsi Anda, dan menghasilkan dokumentasi yang sesuai untuk Anda.

Namun apa yang membedakan dokumentasi hebat dari dokumentasi yang memadai adalah penyertaan contoh penggunaan dan, idealnya, tutorial. Inilah yang membantu pengguna memahami API Anda dan dari mana harus memulai. Ini mengarahkan mereka dan membantu mereka memuat API Anda ke otak mereka.

Misalnya, jika pengembang Twilio ingin membuat daftar setiap kelas, setiap metode, dan setiap kemungkinan respons terhadap API mereka, tetapi tidak repot-repot menyebutkan bahwa Anda dapat mengirim SMS, melacak panggilan, atau membeli nomor telepon melalui API mereka, akan membutuhkan waktu yang sangat lama bagi pengguna API untuk menemukan informasi tersebut dan memahaminya secara terpadu. Dapatkah Anda membayangkan memilah-milah pohon kelas dan metode raksasa tanpa wawasan tentang apa yang mereka gunakan, selain nama mereka? Kedengarannya mengerikan bukan? Tapi itulah yang dilakukan oleh banyak penyedia API, sehingga membuat API mereka tidak terlihat oleh siapa pun kecuali diri mereka sendiri. Panduan pengembang dan API Rackspace CloudFiles adalah salah satu contohnya; sulit untuk mendapatkan bantalan Anda kecuali Anda sudah memahami apa yang mereka lakukan dan apa yang mereka berikan.

Jadi, tulislah tutorial singkat yang membantu pengembang untuk aktif dan berjalan dengan cepat, dengan setidaknya kerangka dari apa yang mereka coba lakukan, dan kemudian arahkan mereka ke daftar fungsionalitas yang lebih rinci dan terdokumentasi sepenuhnya sehingga mereka dapat berkembang pada apa yang mereka miliki.

Setelah Anda selesai dengan dokumentasi Anda, pastikan untuk memvalidasi bahwa itu masuk akal bagi orang lain selain Anda sendiri. Kirimkan ke pengembang lain di jaringan Anda, jangan beri mereka instruksi selain mengarahkan mereka ke dokumentasi, dan minta mereka untuk mengikuti tutorial atau membangun sesuatu yang sangat mendasar dalam waktu sekitar 15 menit. Jika mereka tidak dapat memiliki integrasi dasar dengan API Anda dalam 15 menit, Anda memiliki lebih banyak pekerjaan yang harus dilakukan.

Untuk beberapa contoh penting dari dokumentasi yang sangat baik dan terperinci, lihat Twilio, Django, dan MailChimp. Tak satu pun dari produk ini yang terbaik di pasar mereka (walaupun semuanya adalah produk bagus), namun mereka membedakan diri mereka sendiri dengan menyediakan beberapa dokumentasi terbaik di pasar mereka, yang tentunya telah memfasilitasi penerimaan luas dan pangsa pasar mereka.

Aturan 2: Stabilitas dan Konsistensi

Jika Anda pernah menggunakan API Facebook, Anda tahu seberapa sering mereka tidak lagi menggunakan dan sepenuhnya menulis ulang API mereka. Tidak peduli seberapa besar Anda menghormati budaya peretas mereka, atau produk mereka, mereka bukanlah perspektif yang ramah pengembang. Alasan mereka masih sukses adalah karena mereka memiliki satu miliar pengguna, bukan karena API mereka hebat.

Tetapi Anda mungkin tidak memiliki kemewahan seperti basis pengguna dan pangsa pasar yang sangat besar, jadi Anda akan membutuhkan API yang jauh lebih tidak stabil, menjaga versi lama tetap berjalan dan didukung untuk jangka waktu yang cukup lama. Mungkin bahkan bertahun-tahun. Jadi untuk itu, berikut adalah beberapa tips dan trik.

Katakanlah, misalnya, bahwa API Anda dapat diakses melalui URL http://myapisite.com/api/widgets dan memberikan responsnya dalam format JSON. Meskipun ini mungkin tampak baik-baik saja pada awalnya, apa yang terjadi ketika Anda perlu mengubah format respons JSON? Semua orang yang sudah terintegrasi dengan Anda akan hancur. Ups.

Jadi, lakukan beberapa perencanaan ke depan, dan buat versi API Anda dari awal, secara eksplisit memasukkan nomor versi ke dalam URL (mis., http://myapisite.com/api/widgets?version=1 atau http://myapisite.com/api/widgets/v1 ) sehingga orang dapat mengandalkan versi 1 yang berfungsi dan dapat meningkatkan ke versi berikutnya saat mereka siap melakukannya. Jika Anda perlu menghapus versi sebelumnya di beberapa titik, silakan, tetapi berikan banyak pemberitahuan dan tawarkan semacam rencana transisi.

Skema URL yang baik akan menyertakan versi utama dalam URL. Setiap perubahan pada format output atau tipe data yang didukung akan menghasilkan versi utama yang baru. Secara umum, dapat diterima untuk menyimpan versi yang sama jika semua yang Anda lakukan adalah menambahkan kunci atau node ke output Anda, tetapi untuk amannya, setiap kali output berubah, benturkan versi.

Selain stabil dari waktu ke waktu, API harus konsisten secara internal. Saya telah melihat banyak API yang mengubah nama parameter atau metode POSTing data, tergantung pada titik akhir yang digunakan. Sebagai gantinya, Anda harus menangani parameter umum secara global dalam API Anda dan menggunakan warisan atau arsitektur bersama untuk menggunakan kembali konvensi penamaan yang sama dan penanganan data secara konsisten di seluruh API Anda.

Terakhir, Anda perlu merekam dan memublikasikan log perubahan untuk menunjukkan perbedaan antara versi API Anda sehingga pengguna tahu persis cara meningkatkan versi.

Aturan 3: Fleksibilitas

Sampah masuk, sampah keluar (GIGO) adalah mantra yang terkenal bagi sebagian besar programmer. Seperti yang diterapkan pada desain API web, prinsip panduan ini cenderung mendikte pendekatan yang cukup kaku untuk meminta validasi. Kedengarannya bagus, bukan? Tidak ada kekacauan, tidak ada masalah.

Namun seperti segala sesuatu, perlu ada keseimbangan. Karena tidak mungkin mengantisipasi setiap cara yang diinginkan pengguna untuk menggunakan layanan Anda, dan karena tidak setiap platform klien konsisten (yaitu, tidak setiap platform memiliki dukungan JSON yang sangat baik, pustaka OAuth yang layak, dll.), ada baiknya untuk memiliki setidaknya beberapa tingkat fleksibilitas atau toleransi sehubungan dengan kendala input dan output Anda.

Misalnya, banyak API akan mendukung berbagai format output, seperti JSON, YAML, XML, et. al., tetapi hanya akan mendukung penentuan format di URL itu sendiri. Dengan semangat untuk tetap fleksibel, Anda dapat mengizinkan ini juga ditentukan dalam URL (mis., /api/v1/widgets.json ), atau Anda juga dapat membaca dan mengenali header HTTP Accept: application/json , atau mendukung variabel querystring seperti ?format=JSON , dan seterusnya.

Dan sementara kami melakukannya, mengapa tidak mengizinkan format yang ditentukan menjadi case-insensitive, sehingga pengguna dapat menentukan ?format=json juga? Itu adalah contoh klasik dari cara untuk mengurangi rasa frustrasi yang tidak perlu bagi pengguna API Anda.

Contoh lain adalah memungkinkan berbagai cara memasukkan variabel. Jadi, seperti halnya Anda memiliki berbagai format output, izinkan juga berbagai format input (misalnya, variabel POST biasa, JSON, XML, dll.). Anda setidaknya harus mendukung variabel POST standar, dan banyak aplikasi modern juga mendukung JSON, jadi keduanya adalah tempat yang baik untuk memulai.

Intinya di sini adalah Anda tidak boleh berasumsi bahwa semua orang berbagi preferensi teknis Anda. Dengan sedikit riset tentang cara kerja API lain, dan melalui dialog dengan pengembang lain, Anda dapat memperoleh alternatif berharga lain yang berguna dan memasukkannya ke dalam API Anda.

Aturan 4: Keamanan

Keamanan jelas merupakan salah satu hal terpenting untuk dibangun ke dalam layanan web Anda, tetapi begitu banyak pengembang yang membuatnya sangat sulit untuk digunakan. Sebagai penyedia API, Anda harus menawarkan contoh yang dapat digunakan tentang cara mengautentikasi dan memberi otorisasi saat mengakses API Anda. Ini seharusnya bukan masalah yang sulit yang menghabiskan waktu berjam-jam bagi pengguna akhir untuk mengerjakannya. Buatlah tujuan Anda bahwa mereka tidak perlu menulis kode apa pun, atau mereka membutuhkan waktu kurang dari 5 menit untuk menulisnya.

Untuk sebagian besar API, saya lebih suka otentikasi berbasis token sederhana, di mana token adalah hash acak yang diberikan kepada pengguna dan mereka dapat mengatur ulang kapan saja jika telah dicuri. Izinkan token untuk diteruskan melalui POST atau header HTTP. Misalnya, pengguna dapat (dan harus) mengirim token SHA-1 sebagai variabel POST, atau sebagai header dalam format seperti “Otorisasi: da39a3ee5e6b4b0d3255bfef95601890afd80709”.

Juga, pilih token yang aman, bukan pengenal numerik pendek. Sesuatu yang tidak dapat diubah adalah yang terbaik. Misalnya, relatif mudah untuk membuat token SHA selama pembuatan pengguna dan menyimpannya di database. Kemudian, Anda cukup menanyakan database Anda untuk setiap pengguna yang cocok dengan token itu. Anda juga dapat membuat token yang dibuat dengan pengidentifikasi unik dan nilai garam, seperti SHA(User.ID + "abcd123") , lalu meminta pengguna mana pun yang cocok; misalnya, where TokenFromPost = SHA(User.ID + "abcd123") .

Pilihan lain yang sangat bagus adalah OAuth 2 + SSL. Anda harus tetap menggunakan SSL, tetapi OAuth 2 cukup sederhana untuk diterapkan di sisi server, dan pustaka tersedia untuk banyak bahasa pemrograman umum.

Jika API yang Anda buat seharusnya dapat diakses di situs web publik melalui JavaScript, Anda juga perlu memastikan bahwa Anda memvalidasi daftar URL per akun untuk token tersebut. Dengan begitu, tidak ada yang bisa memeriksa panggilan ke API Anda, mencuri token dari pengguna Anda, dan menggunakannya sendiri.

Berikut adalah beberapa hal penting lainnya yang perlu diingat:

• Fungsi Daftar Putih. API umumnya memungkinkan Anda melakukan operasi dasar membuat, membaca, memperbarui, dan menghapus data. Tetapi Anda tidak ingin mengizinkan operasi ini untuk setiap entitas, jadi pastikan masing-masing memiliki daftar putih tindakan yang diizinkan. Pastikan, misalnya, bahwa hanya pengguna yang berwenang yang dapat menjalankan perintah seperti /user/delete/<id> . Demikian pula, semua tajuk berguna yang dikirim dalam permintaan pengguna juga perlu divalidasi dengan daftar putih. Jika Anda mengizinkan header tipe Konten, verifikasi bahwa apa pun yang dikirim pengguna benar-benar cocok dengan daftar sementara tipe konten yang didukung. Jika tidak, kirim kembali pesan kesalahan seperti respons 406 Tidak Dapat Diterima. Daftar putih penting karena banyak API dibuat secara otomatis, atau menggunakan daftar hitam sebagai gantinya, yang berarti Anda harus eksplisit tentang apa yang tidak Anda inginkan. Namun, aturan utama keamanan adalah memulai dengan benar-benar tidak ada, dan hanya mengizinkan secara eksplisit apa yang Anda inginkan .

• Lindungi diri Anda dari Pemalsuan Permintaan Lintas Situs (CSRF). Jika Anda mengizinkan otentikasi sesi atau cookie, Anda perlu memastikan bahwa Anda melindungi diri Anda dari serangan CSRF. Proyek Keamanan Aplikasi Web Terbuka (OWASP) memberikan panduan yang berguna tentang cara untuk mencegah kerentanan ini.

• Validasi akses ke sumber daya. Dalam setiap permintaan, Anda perlu memverifikasi bahwa pengguna sebenarnya diizinkan mengakses item tertentu yang mereka rujuk. Jadi, jika Anda memiliki titik akhir untuk melihat detail kartu kredit pengguna (misalnya, /account/card/view/152423 ), pastikan bahwa ID "152423" merujuk ke sumber daya yang benar-benar diizinkan untuk diakses oleh pengguna.

• Validasi semua masukan. Semua masukan dari pengguna harus diurai dengan aman, sebaiknya menggunakan pustaka terkenal jika Anda menggunakan masukan yang rumit seperti XML atau JSON. Jangan membangun parser Anda sendiri, atau Anda berada dalam dunia yang terluka.

Aturan 5: Kemudahan Adopsi

Ini benar-benar aturan yang paling penting dalam kelompok itu, dan dibangun di atas yang lainnya. Seperti yang saya sebutkan selama aturan dokumentasi, coba ini dengan orang-orang yang baru mengenal API Anda. Pastikan mereka dapat aktif dan berjalan dengan setidaknya implementasi dasar API Anda, meskipun hanya mengikuti tutorial, dalam beberapa menit. Saya pikir 15 menit adalah tujuan yang bagus.

Berikut adalah beberapa rekomendasi khusus untuk memudahkan dan memfasilitasi adopsi API Anda:

• Pastikan orang benar-benar dapat menggunakan API Anda dan itu berfungsi pertama kali, setiap saat. Minta orang baru untuk mencoba mengimplementasikan API Anda sesekali untuk memverifikasi bahwa itu tidak membingungkan dalam beberapa hal yang membuat Anda kebal.

• Tetap sederhana. Jangan lakukan otentikasi mewah. Jangan lakukan skema URL khusus yang gila. Jangan menemukan kembali SOAP, atau JSON, atau REST, atau apa pun. Gunakan semua alat yang Anda bisa yang telah diterapkan dan diterima secara luas, sehingga pengembang hanya perlu mempelajari API Anda, bukan API + 10 Anda yang mengaburkan teknologi baru.

• Sediakan perpustakaan khusus bahasa untuk berinteraksi dengan layanan Anda. Ada beberapa alat yang bagus untuk membuat perpustakaan secara otomatis untuk Anda, seperti Alpaca atau Apache Thrift. Saat ini Alpaca mendukung Node, PHP, Python, dan Ruby. Hemat mendukung C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Kakao, JavaScript, Node.js, Smalltalk, OCaml, Delphi dan banyak lagi.

• Sederhanakan pendaftaran yang diperlukan. Jika Anda tidak mengembangkan API open source, atau jika ada proses pendaftaran apa pun, pastikan bahwa saat mendaftar, pengguna diarahkan ke tutorial dengan sangat cepat. Dan buat proses pendaftaran sepenuhnya otomatis tanpa perlu interaksi manusia di pihak Anda.

• Memberikan dukungan yang sangat baik. Hambatan besar untuk adopsi adalah kurangnya dukungan. Bagaimana Anda akan menangani dan menanggapi laporan bug? Bagaimana dengan dokumentasi yang tidak jelas? Pengguna yang tidak canggih? Forum, pelacak bug, dan dukungan email adalah awal yang luar biasa, tetapi pastikan bahwa ketika seseorang memposting bug, Anda benar-benar mengatasinya. Tak seorang pun ingin melihat forum kota hantu atau daftar besar bug yang belum ditangani.

Rangkuman API Web

Layanan web dan API mereka berlimpah. Sayangnya, sebagian besar sulit digunakan. Alasannya berkisar dari desain yang buruk, kurangnya dokumentasi, hingga volatilitas, hingga bug yang belum terselesaikan, atau, dalam beberapa kasus, semua hal di atas.

Mengikuti panduan dalam posting ini akan membantu memastikan bahwa API web Anda bersih, terdokumentasi dengan baik, dan mudah digunakan. API semacam itu benar-benar langka dan oleh karena itu lebih mungkin untuk diadopsi dan digunakan secara luas.