Bagaimana cara mendesain pesan kesalahan API?

Hai! Sebagai penyedia API, saya sudah cukup lama merancang pesan kesalahan API. Ini mungkin tampak seperti bagian kecil dari keseluruhan API, tapi percayalah, ini dapat meningkatkan atau menghancurkan pengalaman pengguna. Di blog ini saya akan berbagi beberapa tips bagaimana merancang pesan error API yang benar-benar berguna.

Pertama, mari kita bahas mengapa pesan kesalahan yang baik itu penting. Ketika pengguna mengalami kesalahan saat menggunakan API Anda, itu bisa sangat membuat frustrasi. Mereka mungkin sedang melakukan sesuatu yang penting, dan tiba-tiba, mereka terjebak. Pesan kesalahan yang dirancang dengan baik dapat mengubah momen frustasi tersebut menjadi kesempatan pembelajaran. Ini dapat membantu pengguna memahami apa yang salah dan bagaimana memperbaikinya, sehingga menghemat waktu dan sakit kepala mereka.

Jelas dan Ringkas

Hal terpenting tentang pesan kesalahan adalah pesan tersebut harus jelas. Anda tidak ingin menggunakan jargon atau bahasa yang terlalu teknis yang mungkin tidak dipahami pengguna. Misalnya, daripada mengatakan "Ada masalah dengan kode status Entitas Tidak Dapat Diproses HTTP 422 karena pelanggaran batasan integritas data yang ditentukan dalam skema", Anda dapat mengatakan "Data yang Anda kirim tidak cocok dengan format yang diperlukan. Silakan periksa masukan Anda dan coba lagi."

Penting juga untuk bersikap ringkas. Pengguna tidak ingin membaca paragraf yang panjang dan berliku untuk mencari tahu apa yang salah. Jaga agar pesan Anda tetap singkat dan langsung pada sasaran. Aturan praktis yang baik adalah menargetkan tidak lebih dari dua atau tiga kalimat.

Berikan Informasi yang Dapat Ditindaklanjuti

Pesan kesalahan seharusnya tidak hanya memberi tahu pengguna apa yang salah namun juga memberi mereka gambaran tentang cara memperbaikinya. Misalnya, jika pengguna mencoba mengakses titik akhir yang memerlukan autentikasi dan mereka belum memberikan kredensial yang valid, pesan kesalahannya mungkin berbunyi "Anda perlu memberikan kredensial autentikasi yang valid untuk mengakses titik akhir ini. Harap sertakan kunci API Anda di header permintaan."

Katakanlah Anda adalah penyedia API untuk distributor farmasi, dan Anda memiliki titik akhir untuk obat-obatan sejenisnyaKrizotinib,Brigatinib, DanCapmatinib Hidroklorida Hidrat. Jika pengguna mencoba mendapatkan informasi tentang suatu obat tetapi menggunakan ID obat yang salah, pesan kesalahan Anda mungkin berbunyi "ID obat yang Anda berikan salah. Silakan periksa ID dan coba lagi. Anda dapat menemukan ID yang benar di halaman dokumentasi kami."

Gunakan Pemformatan yang Konsisten

Konsistensi adalah kunci dalam menangani pesan kesalahan. Gunakan format yang sama untuk semua pesan kesalahan di seluruh API Anda. Hal ini memudahkan pengguna untuk memahami dan memproses informasi dengan cepat. Misalnya, Anda dapat memulai semua pesan kesalahan dengan judul deskriptif singkat yang dicetak tebal, diikuti dengan penjelasan yang lebih detail.

**Error: Input Tidak Valid** Input yang Anda berikan pada kolom nama obat tidak valid. Itu harus berupa string tanpa karakter khusus. Harap perbaiki masukannya dan coba lagi.

Sertakan Kode Kesalahan

Kode kesalahan adalah cara terbaik untuk memberikan informasi lebih detail kepada pengembang. Mereka dapat menggunakan kode ini untuk mengidentifikasi dan memecahkan masalah dalam aplikasi mereka dengan cepat. Pastikan kode kesalahan Anda unik dan mudah dimengerti. Anda dapat memiliki bagian terpisah dalam dokumentasi API Anda yang menjelaskan arti setiap kode kesalahan.

Misalnya, Anda mungkin memiliki kode kesalahan "ERR - 001" untuk "Kunci API Tidak Valid" dan kode kesalahan "ERR - 002" untuk "Parameter yang Diperlukan Tidak Ada". Pesan kesalahan Anda kemudian dapat berbunyi seperti "Kode kesalahan: ERR - 001. Kunci API yang Anda berikan tidak valid. Silakan periksa kunci Anda dan coba lagi."

Menawarkan Informasi Dukungan

Terkadang, pengguna mungkin memerlukan bantuan lebih dari apa yang dapat diberikan oleh pesan kesalahan. Dalam kasus ini, sebaiknya sertakan informasi dukungan dalam pesan kesalahan Anda. Ini bisa berupa tautan ke halaman dukungan Anda, alamat email, atau forum tempat pengguna dapat mengajukan pertanyaan.

Misalnya, "Jika Anda masih mengalami masalah setelah mengikuti langkah-langkah di atas, silakan kunjungi halaman dukungan kami untuk bantuan lebih lanjut."

Uji Pesan Kesalahan Anda

Sebelum Anda merilis API ke publik, pastikan untuk menguji pesan kesalahan Anda secara menyeluruh. Cobalah berbagai skenario yang dapat memicu kesalahan dan lihat bagaimana tampilan dan nuansa pesan. Anda juga bisa mendapatkan masukan dari pengembang atau pengguna lain untuk melihat apakah pesannya jelas dan bermanfaat.

Pertimbangkan Lokalisasi

Jika API Anda digunakan oleh audiens global, Anda mungkin ingin mempertimbangkan untuk melokalkan pesan kesalahan Anda. Ini berarti menyediakan pesan dalam berbagai bahasa. Ini dapat membuat perbedaan besar dalam pengalaman pengguna bagi yang bukan penutur bahasa Inggris.

Kesimpulan

Merancang pesan kesalahan API yang baik adalah bagian penting dalam menjadi penyedia API. Dengan memberikan informasi yang jelas, ringkas, dan dapat ditindaklanjuti, Anda dapat membantu pengguna mendapatkan pengalaman yang lebih baik saat menggunakan API Anda. Ingatlah untuk menggunakan pemformatan yang konsisten, sertakan kode kesalahan, tawarkan informasi dukungan, uji pesan Anda, dan pertimbangkan pelokalan jika diperlukan.

Jika Anda tertarik menggunakan API kami untuk kebutuhan distribusi farmasi Anda, baik untukKrizotinib,Brigatinib, atauCapmatinib Hidroklorida Hidrat, kami ingin ngobrol dengan Anda. Hubungi kami untuk memulai proses pengadaan dan negosiasi.

Referensi

• Praktik Terbaik Desain API RESTful, O'Reilly Media
• Desain API untuk Pengembang, Pengembang Google