Tulis status sebelum menggambar animasi pemuatan
Ini adalah usulan alur untuk aplikasi pendakian milik pengembang, bukan catatan perilaku API yang telah diamati. Pendaki memasukkan offline maps, meminta diskusi historis, lalu menunggu. Aplikasi perlu membedakan formulir yang belum disentuh, permintaan belum selesai, rekaman yang diterima, respons kosong yang berhasil, dan kegagalan. Satu panel kosong tidak bisa menjelaskan semua keadaan tersebut.
Mulai dengan layar netral yang menjelaskan apa yang akan dicari. Mengetik saja tidak harus mengirim permintaan. Saat pengguna mengirim secara eksplisit, simpan pertanyaan bersama permintaannya dan tampilkan label memuat. Jaga masukan tetap terbaca dan cegah ketukan berulang mengirim tindakan yang sama beberapa kali. Animasi berputar memberi umpan balik tentang menunggu, bukan bukti kemajuan penelusuran arsip.
Kaitkan respons terlambat dengan pertanyaannya
Bayangkan pendaki mengganti masukan menjadi wilayah yang diunduh ketika permintaan peta offline masih berlangsung. Ini ilustrasi interaksi, bukan hasil pencarian yang diperoleh. Aplikasi harus memutuskan untuk menunggu, memulai permintaan lain, atau mengizinkan pengguna membatalkan tampilan. Pilihan mana pun yang diterapkan, respons lama tidak boleh diam-diam menjadi jawaban untuk frasa baru.
Kaitkan setiap permintaan dengan masukannya dalam status aplikasi sendiri. Saat respons tiba, periksa apakah masih cocok untuk tampilan saat ini. Mengabaikan respons terlambat dari layar tidak sama dengan membatalkan pekerjaan server: permintaan yang sudah terkirim dapat selesai dengan sukses dan dikenai biaya. Uji perbedaan ini dalam implementasi Anda.
Perlakukan keberhasilan kosong sebagai hasil
Untuk rekaman yang diterima, tampilkan field yang benar-benar tersedia dan pertahankan label sumber historis. Jika array data kosong, gunakan pesan terpisah bahwa permintaan ini tidak mengembalikan rekaman. Izinkan pengubahan frasa atau filter sambil mempertahankannya agar pembaca bisa memilih dengan sadar. Jangan mengganti hasil kosong dengan posting populer yang dibuat-buat.
Pengambilan kosong yang berhasil memerlukan satu kredit, sama seperti respons berhasil yang berisi rekaman. Karena itu perubahan kueri harus disengaja, bukan hasil kosong disembunyikan sebagai galat. Hindari klaim bahwa tidak ada diskusi relevan di mana pun; arsip tidak lengkap dan respons memiliki kueri serta jendela terbatas tertentu.
Serahkan masalah teknis kepada operator
Respons 400 memerlukan pemeriksaan masukan. Jika aplikasi mengirim tanggal tak valid atau parameter yang tidak didukung, jangan menyalahkan pendaki atas kesalahan kontrak backend. 401 menunjukkan kunci layanan tidak ada atau tidak valid; memuat ulang aplikasi atau meminta pendaki masuk belum tentu memperbaiki kredensial tersebut.
402 menunjukkan kredit akun layanan tidak cukup. Arahkan keputusan itu ke operator, bukan menampilkan invoice kepada pendaki. 429 mengharuskan kepatuhan terhadap Retry-After dan pengurangan permintaan berulang. Karena aplikasi dapat memakai satu akun untuk banyak pembaca, jangan otomatis mengatakan bahwa seorang pengguna menyebabkan batas itu.
Pisahkan kegagalan yang diketahui dari hasil yang belum diketahui
Gateway mengembalikan 502 ketika pengambilan hulu gagal. Kredit yang direservasi dilepaskan atau dilaporkan masih menunggu rekonsiliasi. Pertahankan kueri dan halaman lama yang sudah terlihat, lalu tawarkan pilihan ulang yang dibatasi. Percobaan otomatis berulang dapat menambah permintaan tanpa membantu pembaca memahami kejadian tersebut.
Jika aplikasi sama sekali tidak menerima respons, aplikasi mungkin tidak tahu apakah server gagal atau selesai. Catat ketidakpastian itu untuk rekonsiliasi; jangan menyatakan pasti berhasil atau pasti dikembalikan. Rute publik /v1/status adalah pemeriksaan statis atas cakupan dan respons HTTP, sehingga tidak dapat menyelesaikan ketidakpastian itu atau memastikan kesehatan pencarian arsip.
Tinjau transisi, bukan hanya gambar layar
Telusuri rangkaian yang diusulkan bersama pemilik aplikasi: kirim, ubah sambil menunggu, terima hasil kosong, coba ulang setelah gagal, muat halaman lain, dan tinggalkan layar. Untuk setiap transisi, tentukan masukan yang disimpan, konten terlihat, dan tindakan berikutnya. Rancangan layar yang menarik tidak membuktikan transisi tersebut bekerja.
Jauhkan diagnosis operator, respons mentah layanan, dan kredensial dari pesan publik. Beri pendaki konteks untuk melanjutkan persiapan tanpa mengandalkan fitur diskusi yang tidak tersedia. Lihat /id/#field-notes untuk keputusan anggaran permintaan dan Tampilkan lagi yang membentuk alur status ini.
