Kode Status HTTP untuk “Still Processing”

Saya sedang membangun API tenang yang mendukung antrian tugas yang sudah berjalan lama untuk penanganan akhirnya.

Alur kerja khas untuk API ini adalah:

1. Pengguna mengisi formulir
2. Klien memposting data ke API
3. Pengembalian API 202 Diterima
4. Klien mengalihkan pengguna ke URL unik untuk permintaan itu ( /results/{request_id})
5. ~ akhirnya ~
6. Klien mengunjungi URL lagi, dan melihat hasilnya di halaman itu.

Masalah saya ada pada langkah 6. Setiap kali pengguna mengunjungi halaman, saya mengajukan permintaan ke API saya ( GET /api/results/{request_id}). Idealnya, tugas sudah selesai sekarang, dan saya akan mengembalikan 200 OK dengan hasil tugas mereka.

Tetapi pengguna memaksa, dan saya berharap banyak refresh bersemangat, ketika hasilnya belum selesai diproses.

Apa pilihan terbaik saya untuk kode status untuk menunjukkan bahwa:

• permintaan ini ada,
• itu belum selesai,
• tetapi juga tidak gagal.

Saya tidak mengharapkan satu kode untuk mengkomunikasikan semua itu, tetapi saya menginginkan sesuatu yang memungkinkan saya melewati metadata alih-alih meminta klien mengharapkan konten.

Masuk akal untuk mengembalikan 202, karena itu tidak akan memiliki arti lain di sini: itu adalah GETpermintaan, jadi tidak ada yang mungkin "diterima." Apakah itu pilihan yang masuk akal?

Alternatif yang jelas untuk semua ini - yang berfungsi, tetapi mengalahkan satu tujuan kode status - akan selalu menyertakan metadata:

200 OK

{
    status: "complete",
    data: {
        foo: "123"
    }
}

...atau...

200 OK

{
    status: "pending"
}

Kemudian sisi klien, saya akan (menghela napas) switchpada response.data.statusuntuk menentukan apakah permintaan tersebut selesai.

Apakah ini yang harus saya lakukan? Atau ada alternatif yang lebih baik? Ini terasa begitu Web 1.0 bagi saya.

HTTP 202 Diterima (HTTP / 1.1)

Anda mencari HTTP 202 Acceptedstatus. Lihat RFC 2616 :

Permintaan telah diterima untuk diproses, tetapi pemrosesan belum selesai.

Pemrosesan HTTP 102 (WebDAV)

RFC 2518 menyarankan menggunakan HTTP 102 Processing:

Kode status 102 (Pemrosesan) adalah respons sementara yang digunakan untuk memberi tahu klien bahwa server telah menerima permintaan lengkap, tetapi belum menyelesaikannya.

tetapi memiliki peringatan:

Server HARUS mengirim respons akhir setelah permintaan selesai.

Saya tidak yakin bagaimana menafsirkan kalimat terakhir. Haruskah server menghindari pengiriman apa pun selama pemrosesan, dan hanya merespons setelah selesai? Atau itu hanya memaksa untuk mengakhiri respons hanya ketika pemrosesan berakhir? Ini bisa bermanfaat jika Anda ingin melaporkan kemajuan. Kirim HTTP 102 dan siram respons byte demi byte (atau baris demi baris).

Misalnya, untuk proses yang panjang tapi linier, Anda dapat mengirim seratus titik, membilas setiap karakter. Jika pihak klien (seperti aplikasi JavaScript) tahu bahwa ia harus mengharapkan tepat 100 karakter, itu dapat mencocokkannya dengan bilah kemajuan untuk ditampilkan kepada pengguna.

Contoh lain menyangkut proses yang terdiri dari beberapa langkah non-linear. Setelah setiap langkah, Anda dapat membuka pesan log yang pada akhirnya akan ditampilkan kepada pengguna, sehingga pengguna akhir dapat mengetahui bagaimana prosesnya.

Masalah dengan pembilasan progresif

Perhatikan bahwa meskipun teknik ini memiliki kelebihan, saya tidak akan merekomendasikannya . Salah satu alasannya adalah bahwa hal itu memaksa koneksi untuk tetap terbuka, yang bisa merugikan dalam hal ketersediaan layanan dan tidak skala dengan baik.

Pendekatan yang lebih baik adalah merespons dengan HTTP 202 Accepteddan membiarkan pengguna untuk kembali kepada Anda nanti untuk menentukan apakah pemrosesan berakhir (misalnya dengan memanggil berulang kali URI yang diberikan seperti /process/resultyang akan merespons dengan HTTP 404 Tidak Ditemukan atau Konflik HTTP 409 hingga proses selesai dan hasilnya siap), atau beri tahu pengguna ketika pemrosesan selesai jika Anda dapat memanggil klien kembali misalnya melalui layanan antrian pesan ( misalnya ) atau WebSockets.

Contoh praktis

Bayangkan sebuah layanan web yang mengkonversi video. Titik masuknya adalah:

POST /video/convert

yang mengambil file video dari permintaan HTTP dan melakukan sihir dengannya. Mari kita bayangkan bahwa sihir itu intensif CPU, jadi itu tidak dapat dilakukan secara real-time selama transfer permintaan. Ini berarti bahwa setelah file ditransfer, server akan merespons dengan HTTP 202 Acceptedbeberapa konten JSON, yang berarti “Ya, saya mendapatkan video Anda, dan saya sedang mengerjakannya; itu akan siap di suatu tempat di masa depan dan akan tersedia melalui ID 123. "

Klien memiliki kemungkinan untuk berlangganan antrian pesan untuk diberi tahu ketika pemrosesan selesai. Setelah selesai, klien dapat mengunduh video yang diproses dengan masuk ke:

GET /video/download/123

yang mengarah ke HTTP 200.

Apa yang terjadi jika klien menanyakan URI ini sebelum menerima pemberitahuan? Nah, server akan merespons HTTP 404karena, memang, videonya belum ada. Saat ini mungkin disiapkan. Itu mungkin tidak pernah diminta. Mungkin ada beberapa waktu di masa lalu dan dihapus kemudian. Yang penting adalah bahwa video yang dihasilkan tidak tersedia.

Sekarang, bagaimana jika klien tidak hanya peduli tentang video akhir, tetapi juga tentang kemajuan (yang akan menjadi lebih penting jika tidak ada layanan antrian pesan atau mekanisme serupa)?

Dalam hal ini, Anda dapat menggunakan titik akhir lain:

GET /video/status/123

yang akan menghasilkan respons yang mirip dengan ini:

HTTP 200
{
    "id": 123,
    "status": "queued",
    "priority": 2,
    "progress-percent": 0,
    "submitted-utc-time": "2016-04-19T13:59:22"
}

Melakukan permintaan berulang kali akan menunjukkan kemajuan sampai:

HTTP 200
{
    "id": 123,
    "status": "done",
    "progress-percent": 100,
    "submitted-utc-time": "2016-04-19T13:59:22"
}

Sangat penting untuk membuat perbedaan antara ketiga jenis permintaan:

• POST /video/convertmengantri tugas. Ini harus dipanggil hanya sekali: memanggilnya lagi akan mengantri tugas tambahan.
• GET /video/download/123menyangkut hasil operasi: sumber daya adalah video. Pemrosesan — itulah yang terjadi di bawah tenda untuk menyiapkan hasil aktual sebelum permintaan dan secara independen terhadap permintaan — tidak relevan di sini. Itu dapat dipanggil sekali atau beberapa kali.
• GET /video/status/123menyangkut pemrosesan per se . Itu tidak mengantri apa pun. Itu tidak peduli dengan video yang dihasilkan. Sumber daya adalah proses itu sendiri. Itu dapat dipanggil sekali atau beberapa kali.

Alternatif yang jelas untuk semua ini - yang berfungsi, tetapi mengalahkan satu tujuan kode status - akan selalu menyertakan metadata:

Ini cara yang tepat untuk pergi. Status sumber daya dalam kaitannya dengan log khusus domain (alias logika bisnis) adalah masalah untuk tipe konten representasi sumber daya.

Ada dua konsep perbedaan yang disatukan di sini yang sebenarnya berbeda. Salah satunya adalah status transfer negara antara klien dan server sumber daya, dan yang lainnya adalah keadaan sumber daya itu sendiri dalam konteks apa pun yang dilakukan domain bisnis terhadap berbagai status sumber daya itu. Yang terakhir tidak ada hubungannya dengan kode status HTTP.

Ingat kode status HTTP sesuai dengan transfer negara antara klien dan server sumber daya yang ditangani, secara independen ke setiap detail sumber daya itu. Ketika Anda GETsumber daya klien Anda meminta server untuk representasi dari sumber daya dalam keadaan saat ini. Itu bisa menjadi gambar burung, itu bisa menjadi dokumen Word, itu bisa menjadi temp luar saat ini. Protokol HTTP tidak peduli. Kode status HTTP sesuai dengan hasil permintaan itu. Apakah POSTdari klien ke server mentransfer sumber daya ke server, di mana server kemudian memberikan URL yang dapat dilihat klien? Iya? Maka itu adalah 201 Createdrespons.

Sumber daya bisa berupa pemesanan maskapai yang saat ini dalam kondisi 'untuk ditinjau'. Atau bisa juga pesanan pembelian produk yang dalam kondisi 'disetujui'. Status tersebut adalah spesifik domain dan bukan tentang protokol HTTP. Protokol HTTP berkaitan dengan transfer sumber daya antara klien dan server.

Maksud dari REST dan HTTP adalah bahwa protokol tidak memperhatikan dirinya sendiri dengan rincian sumber daya. Ini sengaja, tidak berkaitan dengan masalah khusus domain sehingga dapat digunakan tanpa harus tahu apa-apa tentang masalah khusus domain. Anda tidak menafsirkan ulang arti kode status HTTP dalam setiap konteks yang berbeda (sistem pemesanan maskapai, sistem pemrosesan bayangkan, sistem keamanan video, dll.).

Hal-hal khusus domain adalah untuk klien dan server untuk mencari tahu di antara mereka sendiri berdasarkan pada Content Typesumber daya. Protokol HTTP agnostik untuk ini.

Adapun cara klien mengetahui bahwa sumber daya Permintaan telah berubah status, pemungutan suara adalah taruhan terbaik Anda karena tetap mengendalikan di klien dan tidak menganggap koneksi tidak terputus. Terutama jika itu akan berpotensi berjam-jam sampai negara berubah. Bahkan jika Anda mengatakan persetan dengan REST Anda hanya akan menjaga koneksi tetap terbuka, menjaganya tetap terbuka selama berjam-jam dan dengan asumsi tidak ada yang salah akan menjadi ide yang buruk. Bagaimana jika pengguna menutup klien atau jaringan padam. Jika rinciannya adalah jam, klien hanya dapat meminta status setiap beberapa menit sampai Permintaan berubah dari 'menunggu' menjadi 'selesai'.

Harapan itu membantu memperjelas hal-hal

Saya menemukan saran dari blog ini masuk akal: REST dan pekerjaan jangka panjang .

Untuk meringkas:

1. Server mengembalikan kode "202 Diterima" dengan tajuk "Lokasi" diatur ke URI untuk klien untuk memeriksa status, mis. "/ Antrian / 12345".
2. Hingga pemrosesan selesai, server merespons permintaan status dengan "200 OK" dan beberapa data respons menampilkan status pekerjaan.
3. Setelah pemrosesan selesai, server merespons permintaan status dengan "303 See Other" dan "Location" yang berisi URI ke hasil akhir.

Kode Status HTTP untuk Sumber Daya belum tersedia menyarankan untuk mengembalikan respons konflik 409, daripada respons 404, dalam hal sumber daya tidak ada karena sedang dibuat.

Dari spesifikasi w3 :

10.4.10 409 Konflik

Permintaan tidak dapat diselesaikan karena konflik dengan kondisi sumber daya saat ini. Kode ini hanya diperbolehkan dalam situasi di mana diharapkan pengguna dapat menyelesaikan konflik dan mengirimkan kembali permintaan. Badan respons HARUS menyertakan cukup

informasi bagi pengguna untuk mengenali sumber konflik. Idealnya, entitas respons akan mencakup informasi yang cukup bagi pengguna atau agen pengguna untuk memperbaiki masalah; Namun, itu mungkin tidak mungkin dan tidak diperlukan.

Konflik kemungkinan besar terjadi sebagai respons terhadap permintaan PUT. Misalnya, jika versi sedang digunakan dan entitas yang PUT menyertakan perubahan ke sumber daya yang bertentangan dengan yang dibuat oleh permintaan sebelumnya (pihak ketiga), server mungkin menggunakan respons 409 untuk menunjukkan bahwa ia tidak dapat menyelesaikan permintaan . Dalam hal ini, entitas respons kemungkinan akan berisi daftar perbedaan antara dua versi dalam format yang ditentukan oleh Tipe Konten respons.

Ini agak canggung, karena kode 409 "hanya diperbolehkan dalam situasi di mana diharapkan pengguna dapat menyelesaikan konflik dan mengirim kembali permintaan." Saya sarankan badan respons menyertakan pesan (mungkin dalam beberapa format respons yang cocok dengan API Anda yang lain) seperti, "Sumber daya ini sedang dibuat. Ini dimulai pada [WAKTU] dan diperkirakan selesai pada [WAKTU]. Silakan coba lagi nanti."

Perhatikan bahwa saya hanya akan menyarankan pendekatan 409 jika sangat mungkin bahwa pengguna yang meminta sumber daya juga adalah pengguna yang memprakarsai generasi sumber daya itu. Pengguna yang tidak terlibat dengan pembuatan sumber daya akan menemukan kesalahan 404 kurang membingungkan.