Apa Itu Kode Status 202 Accepted? "Saya Tangani Ini" dari API

Anda baru saja mengklik tombol untuk menjalankan laporan kompleks. Atau mungkin Anda telah meminta pekerjaan transkoding video. Alih-alih halaman membeku selama beberapa menit, Anda segera mendapatkan pesan: "Permintaan Anda telah diterima untuk diproses." Beberapa menit kemudian, Anda mendapatkan email dengan tautan ke laporan Anda yang telah selesai.

Pengalaman yang mulus dan asinkron ini adalah ciri khas perangkat lunak modern yang dirancang dengan baik. Dan ini didukung oleh kode status HTTP yang krusial, namun sering disalahpahami: 202 Accepted.

Tidak seperti saudaranya 200 OK, yang berarti "Saya sudah selesai sekarang," atau 201 Created, yang berarti "Saya membuat sesuatu yang baru," kode status 202 Accepted adalah tentang mengelola ekspektasi. Ini adalah cara server mengatakan, "Pesan diterima. Saya mengerti apa yang Anda ingin saya lakukan. Saya tidak bisa memberikan hasilnya sekarang, tetapi saya sudah memasukkannya ke dalam antrean dan saya akan menanganinya. Anda tidak perlu menunggu."

Ini adalah analogi digital dari memberikan tiket Anda kepada pelayan restoran yang sibuk. Mereka tidak langsung membawakan makanan, tetapi Anda percaya bahwa tempat Anda dalam antrean aman dan makanan Anda akan siap pada akhirnya.

Jika Anda membangun atau menggunakan API yang menangani tugas-tugas yang berjalan lama, memahami 202 Accepted adalah kunci untuk menciptakan aplikasi yang responsif, terukur, dan ramah pengguna.

Jadi, apa artinya ini, dan mengapa penting bagi pengembang, penguji, dan konsumen API untuk memahaminya?

Dan sebelum kita masuk ke mekanismenya, jika Anda merancang API yang membutuhkan alur kerja asinkron, Anda memerlukan alat yang dapat membantu Anda menguji dan memvisualisasikan interaksi kompleks ini. Unduh Apidog secara gratis; ini adalah platform API lengkap yang memungkinkan Anda dengan mudah mensimulasikan respons 202, menguji mekanisme polling, dan memastikan proses asinkron Anda kuat dan andal.

button

Sekarang, mari kita bedah apa arti 202 Accepted, kapan menggunakannya, dan bagaimana mengimplementasikannya dengan benar.

Mengatur Panggung: Masalah dengan Pemikiran Sinkron

Untuk memahami mengapa 202 diperlukan, kita harus terlebih dahulu mengenali keterbatasan permintaan sinkron.

Siklus permintaan-respons HTTP yang khas adalah sinkron dan memblokir:

Klien: Mengirim permintaan.
Klien: Menunggu... (ini sering disebut "waktu ke byte pertama" atau TTFB).
Server: Memproses permintaan (ini bisa melibatkan perhitungan kompleks, kueri basis data, memanggil layanan lain).
Server: Mengirim respons (`200 OK`, `201 Created`, dll.).
Klien: Menerima respons dan bertindak berdasarkan itu.

Model ini berfungsi sempurna untuk operasi cepat seperti mengambil profil pengguna, mengambil daftar produk, atau memperbarui satu bidang. Tetapi bagaimana jika operasi tersebut memakan waktu 5 detik? 30 detik? 5 menit?

Koneksi bisa habis waktu (time out), menyebabkan kesalahan.
Browser atau aplikasi pengguna akan tampak membeku, menciptakan pengalaman pengguna yang buruk.
Proses server Anda akan terikat, tidak dapat menangani permintaan masuk lainnya, menyebabkan skalabilitas yang buruk.

Kode status `202 Accepted` adalah solusi elegan untuk masalah ini. Ini memutus sifat pemblokiran HTTP, memungkinkan pemrosesan asinkron.

Apa Sebenarnya Arti HTTP 202 Accepted?

Kode status HTTP `202 Accepted` didefinisikan dalam RFC sebagai respons sukses. Namun, ini adalah jenis sukses yang sangat spesifik. Kode status **202 Accepted** termasuk dalam **kategori 2xx**, yang umumnya menunjukkan keberhasilan. Ini menunjukkan bahwa:

Permintaan telah **diterima dan dipahami**.
Permintaan telah **diterima untuk diproses**.
Pemrosesan **belum selesai**.
Pemrosesan **mungkin atau mungkin tidak pada akhirnya menghasilkan tindakan yang selesai** (bahkan mungkin gagal nanti).

Namun, tidak seperti `200 OK`, yang berarti permintaan berhasil diproses dan selesai, **202 memberi tahu kita sesuatu yang berbeda**:

Server telah menerima permintaan, tetapi pemrosesan belum selesai.

Yang terpenting, respons harus memberikan indikasi kepada klien tentang di mana mereka dapat memeriksa status permintaan atau di mana hasil akhir akan tersedia di masa mendatang.

Dengan kata lain, 202 adalah cara sopan server untuk mengatakan:

"Hei, saya sudah menerima permintaan Anda. Saya sedang mengerjakannya. Tapi jangan berharap hasilnya segera."

Ini membuatnya sangat berguna untuk proses **operasi asinkron** yang memakan waktu, seperti mengirim email, memproses kumpulan data besar, atau memulai pekerjaan latar belakang.

Mengapa 202 Accepted Ada?

Tidak semua permintaan dapat diproses secara instan. Bayangkan jika setiap kali Anda mengirim panggilan API, server harus menunggu sampai seluruh pekerjaan selesai sebelum merespons. Itu bisa menyebabkan:

**Time out** pada tugas-tugas yang berjalan lama.
**Pengalaman pengguna yang buruk** karena klien akan macet.
**Server kelebihan beban**, karena sumber daya terikat sampai pekerjaan selesai.

Kode status **202** memecahkan masalah ini dengan memungkinkan server untuk mengakui permintaan tanpa membuat klien menunggu.

Alur Kerja Asinkron: Penjelasan Langkah demi Langkah

Mari kita bahas contoh konkret. Bayangkan sebuah API untuk menghasilkan laporan data yang dipersonalisasi.

Langkah 1: Permintaan Klien

Aplikasi klien mengirim permintaan `POST` untuk memulai pembuatan laporan.

POST /api/reports/generate HTTP/1.1Host: api.example.comContent-Type: application/jsonAuthorization: Bearer <token>
{
  "type": "annual_sales",
  "year": 2023,
  "format": "pdf"
}

Langkah 2: Respons 202 dari Server

Server menerima permintaan. Server memvalidasi bahwa permintaan diformat dengan baik dan pengguna diotorisasi. Kemudian segera menempatkan pekerjaan ke dalam antrean pemrosesan (menggunakan sistem seperti Redis, RabbitMQ, atau Amazon SQS) dan merespons.

HTTP/1.1 202 AcceptedLocation: <https://api.example.com/api/reports/status/job-12345Content-Type:> application/json
{
  "message": "Your report generation request has been accepted and is being processed.",
  "job_id": "job-12345",
  "status_url": "<https://api.example.com/api/reports/status/job-12345>",
  "estimated_completion_time": "2023-10-27T10:05:00Z"
}

Respons ini sangat kuat. Mari kita bedah:

HTTP/1.1 202 Accepted: Pesan intinya: "Saya sudah menerimanya."
Header `Location`: Header HTTP standar yang menunjuk ke URL tempat status permintaan dapat dipantau. Ini adalah praktik terbaik untuk respons 202.
Isi Respons: Menyediakan informasi yang berguna, dapat dibaca manusia dan mesin tentang apa yang terjadi selanjutnya. `job_id` dan `status_url` sangat penting.

Langkah 3: Pemrosesan Asinkron

Klien sekarang bebas melakukan hal lain. Sementara itu, di server:

Pekerja latar belakang (atau proses) terpisah mengambil pekerjaan dari antrean.
Ia melakukan tugas yang memakan waktu: mengkueri basis data, mengkompilasi data, menghasilkan PDF.
Setelah selesai, ia menyimpan hasilnya (misalnya, di penyimpanan cloud seperti S3) dan memperbarui status pekerjaan menjadi "completed" (selesai).

Langkah 4: Klien Memeriksa Penyelesaian

Klien sekarang dapat melakukan polling `status_url` yang disediakan dalam respons 202.

GET https://api.example.com/api/reports/status/job-12345

Respons terhadap permintaan polling ini mungkin berubah seiring waktu:

Awalnya: {"status": "processing", "progress": 45}
Ketika Selesai: {"status": "completed", "download_url": "<https://api.example.com/api/reports/download/job-12345.pdf>"}

Sebagai alternatif, server dapat mengirimkan notifikasi melalui **webhook** ke URL yang disediakan oleh klien, yang merupakan pola yang lebih canggih dan efisien daripada polling.

Karakteristik Utama 202 Accepted

Berikut adalah ciri-ciri penting dari respons 202:

Permintaan diterima: Server menerima permintaan Anda.
Pemrosesan belum selesai: Pekerjaan sebenarnya masih berlangsung.
Tidak ada jaminan penyelesaian: Tidak seperti 200, 202 tidak menjamin pekerjaan akan berhasil hanya bahwa itu telah diterima.
Berguna untuk alur kerja asinkron: Pekerjaan latar belakang, antrean, atau pemrosesan yang tertunda.

202 Accepted vs. Kode Sukses Lainnya: Mengetahui Perbedaannya

Mudah untuk membingungkan `202` dengan kode 2xx lainnya. Berikut adalah lembar contekan sederhana:

200 OK: "Saya berhasil memproses permintaan Anda *dan* inilah hasilnya *sekarang juga*." (Sinkron, hasil segera)
201 Created: "Saya berhasil membuat sumber daya baru *sekarang juga*. Ini lokasinya dan datanya." (Sinkron, pembuatan segera)
202 Accepted: "Saya akan memproses permintaan Anda. Periksa kembali nanti untuk hasilnya." (Asinkron, pemrosesan tertunda)
204 No Content: "Saya berhasil memproses permintaan Anda, tetapi saya tidak memiliki konten untuk dikirim kembali kepada Anda." (Sinkron, tanpa isi)

Gunakan `202` ketika hasilnya akan tersedia di masa mendatang, bukan segera.

Mengapa Menggunakan 202 Accepted? Manfaat Utama

Pengalaman Pengguna (UX) yang Lebih Baik: Aplikasi klien tetap responsif. Pengguna mendapatkan umpan balik langsung bahwa permintaan mereka diterima, bukan roda berputar yang menunjukkan kesalahan.
Skalabilitas Server yang Lebih Baik: Utas penanganan permintaan utama server segera dibebaskan. Mereka mendelegasikan pekerjaan berat ke pekerja latar belakang, memungkinkan server menangani lebih banyak permintaan masuk.
Menangani Ketidakpastian: Server dapat menerima permintaan meskipun tidak 100% yakin dapat dipenuhi nanti. Misalnya, server mungkin menerima permintaan yang bergantung pada layanan pihak ketiga yang sementara tidak berfungsi.
Realistis untuk Operasi Kompleks: Ini secara akurat memodelkan proses dunia nyata yang memakan waktu, seperti mengirim email, memproses video, menjalankan model pembelajaran mesin, atau menangani ekspor data besar.

Kasus Penggunaan Nyata untuk HTTP 202

Anda akan menemukan `202 Accepted` di banyak aplikasi modern:

Pemrosesan File: Transkoding gambar/video, konversi dokumen (misalnya, pembuatan PDF).
Operasi Data: Pembuatan laporan besar, ekspor/impor data, pengiriman email massal.
AI/Pembelajaran Mesin: Mengirimkan tugas untuk pelatihan atau inferensi model.
Pemrosesan Pembayaran: Beberapa gateway pembayaran menerima permintaan pembayaran secara asinkron.
DevOps/CI-CD: Memicu pipeline build. API menerima permintaan segera dan mengembalikan tautan ke log build.

Manfaat Menggunakan 202 Accepted

Mengapa pengembang dan perancang API harus menggunakan 202?

Mencegah time out klien: Pengguna tidak perlu menunggu.
Meningkatkan skalabilitas: Server tidak terkunci pada tugas-tugas yang panjang.
Umpan balik pengguna yang lebih baik: Alih-alih diam, klien tahu permintaan sedang ditangani.
Mendukung arsitektur asinkron: Penting untuk microservices modern.

202 Accepted dalam Alur Kerja Asinkron

Berikut cara kerjanya secara umum:

Klien mengirim permintaan.
Server merespons dengan 202 dan mungkin "URL status."
Klien memeriksa kembali dengan titik akhir status untuk melihat apakah pekerjaan sudah selesai.

Misalnya:

{
  "status": "processing",
  "check_status": "/jobs/12345/status"
}

Pola ini membuat kedua belah pihak senang: klien mendapatkan pengakuan instan, dan server mendapatkan ruang bernapas.

Menguji Alur Kerja 202 dengan Apidog

Menguji alur API asinkron lebih kompleks daripada menguji panggilan sinkron sederhana. Di sinilah Apidog menjadi alat yang tak ternilai.

Dengan Apidog, Anda dapat:

Menulis Skrip Alur: Buat skenario pengujian yang pertama-tama mengirimkan permintaan `POST` dan memvalidasi bahwa ia mengembalikan `202` dengan `status_url`.
Ekstrak Variabel: Gunakan skrip Apidog untuk secara otomatis mengekstrak `job_id` atau `status_url` dari respons `202` dan menyimpannya sebagai variabel lingkungan.
Uji Polling: Buat permintaan `GET` berikutnya yang menggunakan variabel yang diekstrak untuk memanggil `status_url`. Anda dapat mengkonfigurasi Apidog untuk mencoba kembali permintaan ini sampai mendapatkan status "completed".
Validasi Hasil Akhir: Setelah pekerjaan selesai, tulis pernyataan untuk memvalidasi respons akhir dari URL unduhan.

Ini memungkinkan Anda mengotomatiskan pengujian seluruh perjalanan asinkron, memastikan keandalan dan menangkap regresi.

Cara Menguji Respons 202 Accepted (dengan Apidog)

Di sinilah **Apidog** bersinar. Tidak seperti alat statis, Apidog memungkinkan Anda:

Mengirim permintaan dan mensimulasikan kode status yang berbeda (seperti 202).
Memalsukan titik akhir API untuk menguji alur kerja asinkron.
Mendokumentasikan API sehingga pengembang tahu apa yang diharapkan dari respons 202.
Berkolaborasi dengan anggota tim untuk menyempurnakan penanganan asinkron.

Dengan Apidog, Anda dapat membangun dan menguji **alur kerja 202 end-to-end** dari penerimaan hingga penyelesaian tanpa beralih alat.

button

Potensi Jebakan dan Kesalahpahaman Umum

Meskipun demikian, 202 dapat disalahgunakan. Beberapa jebakan meliputi:

Mengasumsikan penyelesaian: Hanya karena permintaan diterima tidak berarti berhasil.
Tidak menyediakan tindak lanjut: API harus menyertakan cara bagi klien untuk memeriksa status pekerjaan.
Penggunaan berlebihan 202: Jangan menggunakannya untuk operasi sederhana dan segera – itu akan membingungkan klien.

Tantangan dan Praktik Terbaik

Mengimplementasikan `202` dengan benar memerlukan pemikiran yang cermat.

Sediakan Titik Akhir Status: Ini tidak bisa dinegosiasikan. Anda **harus** menyediakan URL (melalui header `Location` atau isi respons) di mana klien dapat memeriksa kemajuan dan hasil akhir permintaan.
Idempoten Itu Penting: Jika klien tidak yakin permintaan mereka berhasil (misalnya, karena masalah jaringan), mereka mungkin mencoba lagi. API Anda harus dirancang untuk menangani permintaan duplikat dengan baik menggunakan **kunci idempoten** untuk mencegah pekerjaan yang sama diantrekan beberapa kali.
Tetapkan Ekspektasi yang Jelas: Gunakan isi respons untuk memberikan perkiraan waktu penyelesaian atau pesan status sederhana (`queued`, `processing`, `failed`, `succeeded`).
Pertimbangkan Webhook: Untuk alternatif yang lebih efisien daripada polling, izinkan klien untuk mendaftarkan URL webhook yang akan dipanggil oleh server Anda ketika pekerjaan selesai.
Rencanakan Kegagalan: Pekerjaan mungkin gagal di latar belakang. Titik akhir status Anda perlu mengkomunikasikan kegagalan dan berpotensi memberikan kode alasan.

Praktik Terbaik untuk Mengimplementasikan 202 Accepted

Jika Anda merancang API yang mengembalikan 202, ingatlah praktik terbaik ini:

Selalu kembalikan konteks: Sediakan ID pekerjaan atau URL status.
Dokumentasikan dengan jelas: Jelaskan bagaimana klien harus memeriksa kemajuan.
Gunakan webhook jika memungkinkan: Beri tahu klien ketika tugas selesai.
Jangan terlalu sering menggunakannya: Hanya kembalikan 202 untuk tugas-tugas yang benar-benar asinkron.

202 Accepted dalam API REST vs GraphQL

API REST: 202 umum karena permintaan sering kali memetakan ke proses yang berjalan lama.
API GraphQL: Kurang umum, karena GraphQL lebih menyukai kueri sinkron, tetapi masih mungkin dengan mutasi asinkron.

Kesimpulan: Merangkul Desain Asinkron

Kode Status HTTP `202 Accepted` adalah alat yang ampuh dalam perangkat desainer API. Ini mewakili pergeseran dari memikirkan API sebagai mekanisme permintaan-respons sederhana menjadi memikirkannya sebagai sistem untuk mengatur alur kerja dunia nyata yang kompleks. Kode status 202 Accepted mungkin bukan kode HTTP yang paling terkenal, tetapi memainkan peran penting dalam alur kerja API asinkron. Ini memberi tahu klien, "Kami telah menerima permintaan Anda, tetapi kami masih mengerjakannya."

Dengan menggunakan `202`, Anda membangun API yang lebih terukur, lebih tangguh, dan memberikan pengalaman yang jauh lebih unggul bagi pengembang yang menggunakannya dan pengguna akhir yang pada akhirnya mendapatkan manfaat darinya.

Ini mengakui bahwa tidak semua hal dalam perangkat lunak terjadi secara instan, dan ini menyediakan cara yang terstandarisasi dan kuat untuk menangani kenyataan itu.

Jadi, lain kali Anda merancang titik akhir untuk tugas yang berjalan lama, jangan memaksanya menjadi sinkron. Rangkullah sifat asinkron dari tugas tersebut. Kembalikan `202 Accepted`, berikan URL status, dan bebaskan aplikasi Anda dari tirani permintaan yang menunggu. Jika Anda membangun atau menguji API yang mengembalikan 202, Anda memerlukan alat yang memungkinkan Anda mensimulasikan, menguji, dan mendokumentasikan alur kerja ini tanpa kerumitan. Itulah yang persis disediakan Apidog. Gunakan alat seperti Apidog untuk memastikan implementasi Anda kuat, dapat diuji, dan menyenangkan untuk diintegrasikan. Siap menyederhanakan pengujian dan dokumentasi API Anda? Unduh Apidog secara gratis hari ini dan jadikan penanganan kode seperti 202 Accepted tanpa usaha.

button