Layar pencarian memerlukan lebih dari hasil atau galat

Storyboard, bukan tampilan kesehatan layanan

Ini adalah status yang diusulkan untuk aplikasi pendakian milik pengembang. Bukan respons API yang direkam, demonstrasi layar yang bekerja, atau bukti tersedianya rekaman tentang peta offline. Pendaki menggunakan aplikasi Anda; operator akun API mengelola kredensial dan kredit layanan. Berikan informasi yang dapat ditindaklanjuti oleh masing-masing pihak.

Sebelum pencarian pertama, jelaskan bahwa fitur membaca diskusi historis. Saran kueri seperti offline maps dapat membantu memulai, tetapi jangan menampilkan rekomendasi rekaan seolah pencarian sudah dijalankan. Pertahankan tindakan Cari yang eksplisit agar mengetik dan menelusuri formulir tidak harus memicu permintaan berbayar.

Saat memuat, pertahankan pertanyaannya

Selama permintaan berlangsung, simpan kueri yang dikirim dan filter pilihan. Tandai area hasil sebagai sedang memuat, cegah pengiriman ganda untuk tindakan itu, dan sertakan label teks yang aksesibel di samping animasi. Keterlambatan saja tidak menunjukkan gangguan layanan atau penyebabnya.

Jika pengguna mengubah kueri sebelum respons sebelumnya datang, kaitkan setiap respons dengan masukan yang dikirim. Jangan diam-diam menaruh hasil pertanyaan lama di bawah pertanyaan baru. Ini adalah pilihan implementasi aplikasi yang perlu diuji, bukan perilaku pengurutan atau pembatalan dari API arsip.

Keberhasilan dapat berisi rekaman atau kosong

Jika rekaman tersedia, tampilkan hanya field yang ada dan nyatakan bahwa materinya historis. Komentar tidak harus memiliki judul, dan tanggal yang hilang harus tetap tidak diketahui. Jelaskan halaman yang terlihat alih-alih mengumumkan jumlah kecocokan persis ketika pagination.relation bernilai gte atau unknown.

Respons kosong yang berhasil merupakan hasil tersendiri. Pesan yang mungkin digunakan: Tidak ada rekaman yang dikembalikan untuk permintaan ini. Tawarkan perubahan kata atau filter secara sengaja sambil mempertahankan masukan lama. Jangan mengklaim bahwa diskusi tersebut tidak ada di mana pun. Pengambilan kosong yang berhasil tetap memerlukan satu kredit.

400, 401, dan 402 menjadi tanggung jawab pihak berbeda

HTTP 400 menunjukkan masukan permintaan tidak valid. Periksa masalah parameter yang sebenarnya, misalnya parameter tak didukung, halaman di luar rentang, atau tanggal yang bukan YYYY-MM-DD. Jika sesuai, jelaskan field yang bisa diperbaiki pendaki; galat kontrak backend masuk ke diagnosis operator.

HTTP 401 berarti kunci API layanan tidak ada atau tidak valid. Itu tidak membuktikan sesi aplikasi pendaki telah berakhir, dan kunci API ini tidak memiliki mekanisme kedaluwarsa berbasis waktu yang terdokumentasi. Operator memeriksa kunci khusus domain yang disimpan dan regenerasi terbaru bila ada. Jangan minta pendaki menyediakan kunci atau masuk ke akun layanan.

HTTP 402 berarti kredit akun layanan tidak cukup. Pesan kepada pendaki bisa menyatakan bahwa pencarian diskusi sementara dijeda. Operator dapat masuk melalui Kunci dan kredit lalu memeriksa saldo. Permintaan baru adalah tindakan terpisah setelah penyebab ditangani; mengulang permintaan lama saja bukan solusi.

429, kegagalan hulu, dan hasil pengiriman yang tidak pasti

HTTP 429 berarti batas laju tercapai. Patuhi Retry-After, kurangi pengiriman berulang, dan izinkan pengguna mencoba lagi pada waktu yang sesuai. Batas dapat melibatkan backend atau akun bersama, jadi jangan menyalahkan seorang pendaki. Hindari perulangan percobaan otomatis tanpa batas.

Gateway melaporkan kegagalan hulu sebagai HTTP 502. Pertahankan kueri dan sediakan pilihan ulang eksplisit tanpa menjanjikan keberhasilan percobaan selanjutnya. Kredit yang direservasi dikembalikan jika permintaan hulu gagal; respons juga dapat menyebut rekonsiliasi tertunda. Jika aplikasi kehilangan respons sepenuhnya, hasil akhir pembiayaan tidak pasti: server mungkin telah menyelesaikannya dengan sukses.

Rute publik /v1/status memberikan pernyataan statis mengenai cakupan layanan dan menunjukkan bahwa penangan HTTP-nya merespons. Rute itu tidak menguji pencarian arsip atau memastikan kesehatan sistem hulu. Dasarkan keputusan operasi pada hasil permintaan sebenarnya. Kembali ke Panduan aplikasi untuk storyboard lengkap, atau ke catatan tentang layar memuat, kosong, dan galat untuk pilihan implementasinya.