Pesan Kesalahan Terstruktur untuk HTTP API

Nicolas Fränkel

Nicolas Fränkel

November 2, 2022

Technology

Sejak saya mulai mengerjakan proyek Apache APISIX, saya telah berusaha meningkatkan pengetahuan dan pemahaman saya tentang REST RESTful HTTP API. Untuk itu, saya membaca dan menonton sumber-sumber berikut:

  • Buku. Saat ini, saya sedang menyelesaikan API Design Patterns. Harap tunggu ulasan segera.
  • YouTube. Saya merekomendasikan saluran ErikWilde. Meskipun beberapa video lebih baik daripada yang lain, semuanya berfokus pada API.
  • IETF RFC. Kebanyakan RFC tidak membahas tentang API, tetapi seseorang yang baik hati telah mengompilasi daftar RFC yang membahas API.

Hari ini, saya ingin memperkenalkan RFC "Problem Details for HTTP APIs", alias RFC 7807.

Masalahnya

Prinsip REST mengharuskan penggunaan status HTTP untuk berkomunikasi. Untuk kesalahan, HTTP mendefinisikan dua rentang: kesalahan klien, 4xx, dan kesalahan server, 5xx.

Bayangkan sebuah API perbankan yang memungkinkan Anda melakukan transfer. API tersebut harus gagal jika Anda mencoba mentransfer lebih banyak dana ke akun Anda. Beberapa kode status HTTP dapat cocok:

  • 400 Bad Request: Server tidak dapat atau tidak akan memproses permintaan karena sesuatu yang dianggap sebagai kesalahan klien.
  • 402 Payment Required: Permintaan tidak dapat diproses sampai klien melakukan pembayaran. Namun, tidak ada konvensi penggunaan standar yang ada, dan entitas yang berbeda menggunakannya dalam konteks lain.
  • 409 Conflict: Permintaan bertentangan dengan status saat ini dari sumber daya target.

Inilah masalah pertama: Kode status HTTP ditentukan untuk interaksi manusia-ke-mesin melalui browser, bukan untuk interaksi mesin-ke-mesin melalui API. Oleh karena itu, memilih kode status yang sesuai satu-ke-satu dengan kasus penggunaan jarang mudah. Sebagai catatan, Martin Fowler tampaknya lebih memilih 409 dalam kasus kita.

Apa pun kode statusnya, masalah kedua berkaitan dengan payload kesalahan atau, lebih tepatnya, strukturnya. Struktur tidak penting jika satu organisasi mengelola klien dan penyedia API. Bahkan jika tim yang berbeda mengembangkan masing-masingnya, mereka dapat menyelaraskannya. Misalnya, bayangkan aplikasi seluler yang memanggil API-nya sendiri.

Namun, masalah muncul ketika sebuah tim memutuskan untuk menggunakan API pihak ketiga. Pilihan struktur respons menjadi signifikan dalam kasus ini karena sekarang dianggap sebagai bagian dari kontrak: setiap perubahan dari penyedia dapat merusak klien. Lebih buruk lagi, strukturnya kemungkinan berbeda dari satu penyedia ke penyedia lainnya.

Oleh karena itu, struktur pelaporan kesalahan yang terstandarisasi:

  • Memberikan keseragaman di antara penyedia
  • Meningkatkan stabilitas API

RFC 7807

RFC 7807 bertujuan untuk menyelesaikan masalah ini dengan menyediakan struktur kesalahan yang terstandarisasi.

Strukturnya adalah sebagai berikut:

Struktur

RFC menjelaskan bidang-bidangnya:

  • "type" (string) - Referensi URI [RFC3986] yang mengidentifikasi jenis masalah. Spesifikasi ini mendorong agar, ketika di-dereferensi, ia menyediakan dokumentasi yang dapat dibaca manusia untuk jenis masalah tersebut (misalnya, menggunakan HTML [W3C.REC-html5-20141028]). Ketika anggota ini tidak ada, nilainya diasumsikan sebagai "about:blank".
  • "title" (string) - Ringkasan singkat yang dapat dibaca manusia tentang jenis masalah. Ini SEHARUSNYA tidak berubah dari kejadian ke kejadian masalah, kecuali untuk tujuan lokalisasi (misalnya, menggunakan negosiasi konten proaktif; lihat [RFC7231, Bagian 3.4]).
  • "status" (number) - ([RFC7231], Bagian 6) yang dihasilkan oleh server asal untuk kejadian masalah ini.
  • "detail" (string) - Penjelasan yang dapat dibaca manusia yang spesifik untuk kejadian masalah ini.
  • "instance" (string) - Referensi URI yang mengidentifikasi kejadian spesifik dari masalah. Ini mungkin atau mungkin tidak memberikan informasi lebih lanjut jika di-dereferensi.

-- Anggota dari Objek Detail Masalah

RFC menawarkan contoh berikut ketika tidak ada cukup dana untuk melakukan transfer perbankan.

Contoh RFC

Contoh

Saya akan menggunakan salah satu demo saya yang sudah ada sebagai contoh. Demo ini menyoroti beberapa langkah untuk mempermudah proses evolusi API Anda.

Pada langkah 6, saya ingin pengguna mendaftar, jadi saya membatasi jumlah panggilan dalam jangka waktu tertentu jika mereka tidak terautentikasi. Saya telah membuat plugin Apache APISIX khusus untuk ini. Setelah jumlah panggilan mencapai batas, plugin mengembalikan:

HTTP/1.1 429 Too Many Requests
Date: Fri, 28 Oct 2022 11:56:11 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.15.0

{"error_msg":"Please register at https:\/\/apisix.org\/register to get your API token and enjoy unlimited calls"}

Mari kita struktur pesan sesuai dengan RFC 7807.

Aturan RFC 7807

Kesimpulan

RFC 7807 tidak hanya membantu pengembang klien. Ini juga sangat membantu bagi pengimplementasi API karena memberikan panduan cepat untuk menghindari penemuan kembali roda di setiap proyek.

Lebih lanjut:

Awalnya diterbitkan di A Java Geek pada 30 Oktober 2022

Tags:
Codec