ما هو كود الحالة 202 مقبول؟: "تلقيت طلبك" في API

لقد نقرت للتو على زر لتشغيل تقرير معقد. أو ربما طلبت مهمة تحويل ترميز الفيديو. بدلاً من تجميد الصفحة لدقائق، تتلقى على الفور رسالة: "تم قبول طلبك للمعالجة." بعد بضع دقائق، تتلقى بريدًا إلكترونيًا يحتوي على رابط لتقريرك النهائي.

هذه التجربة السلسة وغير المتزامنة هي سمة مميزة للبرمجيات الحديثة المصممة جيدًا. وهي مدعومة برمز حالة HTTP حاسم، ولكن غالبًا ما يُساء فهمه: 202 Accepted.

على عكس نظيره 200 OK، الذي يقول "لقد انتهيت الآن"، أو 201 Created، الذي يقول "لقد أنشأت شيئًا جديدًا"، فإن رمز الحالة 202 Accepted يدور حول إدارة التوقعات. إنها طريقة الخادم للقول: "تم استلام الرسالة. أفهم ما تريد مني أن أفعله. لا يمكنني أن أقدم لك النتيجة الآن، لكنني وضعتها في قائمة الانتظار وسأتعامل معها. لا تحتاج إلى الانتظار."

إنها تعادل رقميًا إعطاء تذكرتك لمضيف مطعم مزدحم. لا يقدمون لك الطعام على الفور، لكنك تثق بأن مكانك في الطابور آمن وأن وجبتك ستكون جاهزة في النهاية.

إذا كنت تقوم ببناء أو استخدام واجهات برمجة التطبيقات (APIs) التي تتعامل مع المهام طويلة الأمد، فإن فهم 202 Accepted أمر أساسي لإنشاء تطبيقات سريعة الاستجابة وقابلة للتوسع وسهلة الاستخدام.

إذًا، ماذا يعني هذا، ولماذا من المهم للمطورين والمختبرين ومستهلكي واجهات برمجة التطبيقات فهمه؟

وقبل أن نتعمق في الآليات، إذا كنت تصمم واجهات برمجة تطبيقات تتطلب سير عمل غير متزامن، فأنت بحاجة إلى أداة يمكنها مساعدتك في اختبار وتصور هذه التفاعلات المعقدة. قم بتنزيل Apidog مجانًا؛ إنها منصة API شاملة تتيح لك محاكاة استجابات 202 بسهولة، واختبار آليات الاستقصاء، والتأكد من أن عملياتك غير المتزامنة قوية وموثوقة.

الآن، دعنا نفكك معنى 202 Accepted، ومتى نستخدمه، وكيف نطبقه بشكل صحيح.

تمهيد المشهد: مشكلة التفكير المتزامن

لفهم سبب ضرورة 202، يجب علينا أولاً إدراك قيود الطلبات المتزامنة.

دورة طلب-استجابة HTTP النموذجية متزامنة ومانعة:

1. العميل: يرسل طلبًا.
2. العميل: ينتظر... (يُطلق على هذا غالبًا "وقت البايت الأول" أو TTFB).
3. الخادم: يعالج الطلب (قد يتضمن ذلك حسابات معقدة، استعلامات قاعدة بيانات، استدعاء خدمات أخرى).
4. الخادم: يرسل استجابة (200 OK، 201 Created، إلخ).
5. العميل: يستقبل الاستجابة ويتصرف بناءً عليها.

يعمل هذا النموذج بشكل مثالي للعمليات السريعة مثل جلب ملف تعريف مستخدم، أو استرداد قائمة منتجات، أو تحديث حقل واحد. ولكن ماذا لو استغرقت العملية 5 ثوانٍ؟ 30 ثانية؟ 5 دقائق؟

• قد تنتهي مهلة الاتصال، مما يؤدي إلى أخطاء.
• سيظهر متصفح المستخدم أو تطبيقه متجمدًا، مما يخلق تجربة مستخدم سيئة للغاية.
• ستكون عمليات الخادم مشغولة، وغير قادرة على التعامل مع الطلبات الواردة الأخرى، مما يؤدي إلى ضعف قابلية التوسع.

رمز الحالة 202 Accepted هو الحل الأنيق لهذه المشكلة. إنه يكسر طبيعة HTTP المانعة، مما يسمح بالمعالجة غير المتزامنة.

ماذا يعني HTTP 202 Accepted بالفعل؟

يُعرّف رمز الحالة HTTP 202 Accepted في RFC على أنه استجابة نجاح. ومع ذلك، فهو نوع محدد جدًا من النجاح. ينتمي رمز الحالة 202 Accepted إلى فئة 2xx، والتي تشير بشكل عام إلى النجاح. إنه يشير إلى أن:

• تم استلام الطلب وفهمه.
• تم قبول الطلب للمعالجة.
• المعالجة لم تكتمل بعد.
• المعالجة قد تؤدي أو لا تؤدي في النهاية إلى إجراء مكتمل (قد تفشل لاحقًا).

ومع ذلك، على عكس 200 OK، الذي يعني أن الطلب تمت معالجته بنجاح واكتمل، يخبرنا 202 شيئًا مختلفًا:

لقد قبل الخادم الطلب، لكن المعالجة لم تنته بعد.

والأهم من ذلك، يجب أن تقدم الاستجابة للعميل بعض الإشارات حول مكان التحقق من حالة الطلب أو أين ستتوفر النتيجة النهائية في المستقبل.

بمعنى آخر، 202 هي طريقة الخادم المهذبة للقول:

"مرحبًا، لقد تلقيت طلبك. أنا أعمل عليه. لكن لا تتوقع النتيجة على الفور."

هذا يجعله مفيدًا بشكل خاص لعمليات العمليات غير المتزامنة التي تستغرق وقتًا، مثل إرسال بريد إلكتروني، أو معالجة مجموعة بيانات كبيرة، أو بدء مهمة خلفية.

لماذا يوجد 202 Accepted؟

لا يمكن معالجة جميع الطلبات على الفور. تخيل لو أن كل مرة ترسل فيها استدعاء API، كان على الخادم الانتظار حتى تكتمل المهمة بأكملها قبل الرد. قد يؤدي ذلك إلى:

• انتهاء المهلة في المهام طويلة الأمد.
• تجربة مستخدم سيئة لأن العملاء سيتوقفون عن العمل.
• زيادة تحميل الخادم، حيث يتم ربط الموارد حتى انتهاء المهام.

يحل رمز الحالة 202 هذه المشكلة عن طريق السماح للخوادم بالاعتراف بالطلبات دون جعل العملاء ينتظرون.

سير العمل غير المتزامن: تفصيل خطوة بخطوة

دعنا ننتقل إلى مثال ملموس. تخيل واجهة برمجة تطبيقات لإنشاء تقارير بيانات مخصصة.

الخطوة 1: طلب العميل

يرسل تطبيق العميل طلب POST لبدء إنشاء التقرير.

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

الخطوة 2: استجابة الخادم 202

يستقبل الخادم الطلب. يتحقق من أن الطلب مكتمل التكوين وأن المستخدم مصرح له. ثم يضع المهمة فورًا في قائمة انتظار المعالجة (باستخدام نظام مثل Redis، RabbitMQ، أو Amazon SQS) ويرد.

HTTP/1.1 202 AcceptedLocation: <https://api.example.com/api/reports/status/job-12345Content-Type:> application/json
{
  "message": "تم قبول طلب إنشاء تقريرك وهو قيد المعالجة.",
  "job_id": "job-12345",
  "status_url": "<https://api.example.com/api/reports/status/job-12345>",
  "estimated_completion_time": "2023-10-27T10:05:00Z"
}

هذه الاستجابة قوية بشكل لا يصدق. دعنا نفككها:

• HTTP/1.1 202 Accepted: الرسالة الأساسية: "لقد تلقيتها."
• Location Header: رأس HTTP قياسي يشير إلى عنوان URL حيث يمكن مراقبة حالة الطلب. هذه أفضل ممارسة لاستجابات 202.
• Response Body: يوفر معلومات مفيدة، قابلة للقراءة بواسطة البشر والآلات، حول ما سيحدث بعد ذلك. job_id و status_url حاسمان.

الخطوة 3: المعالجة غير المتزامنة

العميل الآن حر في القيام بأشياء أخرى. في هذه الأثناء، على الخادم:

• يلتقط عامل خلفي منفصل (أو عملية) المهمة من قائمة الانتظار.
• يقوم بالمهمة التي تستغرق وقتًا طويلاً: استعلام قاعدة البيانات، تجميع البيانات، إنشاء ملف PDF.
• بمجرد الانتهاء، يخزن النتيجة (على سبيل المثال، في التخزين السحابي مثل S3) ويحدث حالة المهمة إلى "مكتملة".

الخطوة 4: العميل يتحقق من الاكتمال

يمكن للعميل الآن استقصاء status_url المقدم في استجابة 202.

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

قد تتغير الاستجابة لطلب الاستقصاء هذا بمرور الوقت:

• مبدئيًا: {"status": "processing", "progress": 45}
• عند الاكتمال: {"status": "completed", "download_url": "<https://api.example.com/api/reports/download/job-12345.pdf>"}

بدلاً من ذلك، يمكن للخادم إرسال إشعار عبر webhook إلى عنوان URL يقدمه العميل، وهو نمط أكثر تقدمًا وكفاءة من الاستقصاء.

الخصائص الرئيسية لـ 202 Accepted

فيما يلي السمات الأساسية لاستجابة 202:

• تم استلام الطلب: تلقى الخادم طلبك.
• المعالجة لم تتم: لا تزال المهمة الفعلية جارية.
• لا يوجد ضمان للاكتمال: على عكس 200، لا تعد 202 بنجاح المهمة، بل فقط بقبولها.
• مفيدة لسير العمل غير المتزامن: المهام الخلفية، قوائم الانتظار، أو المعالجة المتأخرة.

202 Accepted مقابل رموز النجاح الأخرى: معرفة الفرق

من السهل الخلط بين 202 ورموز 2xx الأخرى. إليك ورقة غش بسيطة:

• 200 OK: "لقد عالجت طلبك بنجاح وهنا النتيجة الآن." (متزامن، نتيجة فورية)
• 201 Created: "لقد أنشأت موردًا جديدًا بنجاح الآن. إليك موقعه وبياناته." (متزامن، إنشاء فوري)
• 202 Accepted: "سأعالج طلبك. تحقق لاحقًا من النتيجة." (غير متزامن، معالجة مؤجلة)
• 204 No Content: "لقد عالجت طلبك بنجاح، ولكن ليس لدي محتوى لأرسله إليك." (متزامن، لا يوجد نص)

استخدم 202 عندما تكون النتيجة متاحة في المستقبل، وليس على الفور.

لماذا نستخدم 202 Accepted؟ الفوائد الرئيسية

1. تحسين تجربة المستخدم (UX): يظل تطبيق العميل مستجيبًا. يتلقى المستخدمون ملاحظات فورية بأن طلبهم قد تم استلامه، وليس عجلة دوارة للموت.
2. تحسين قابلية توسع الخادم: يتم تحرير سلاسل معالجة الطلبات الرئيسية للخادم على الفور تقريبًا. فهي تفوض العمل الشاق إلى العمال الخلفيين، مما يسمح للخادم بالتعامل مع المزيد من الطلبات الواردة.
3. يتعامل مع عدم اليقين: يمكن للخادم قبول طلب حتى لو لم يكن متأكدًا بنسبة 100٪ من إمكانية تلبيته لاحقًا. على سبيل المثال، قد يقبل طلبًا يعتمد على خدمة طرف ثالث معطلة مؤقتًا.
4. واقعي للعمليات المعقدة: إنه يمثل بدقة العمليات في العالم الحقيقي التي تستغرق وقتًا، مثل إرسال رسائل البريد الإلكتروني، ومعالجة مقاطع الفيديو، وتشغيل نماذج التعلم الآلي، أو التعامل مع عمليات تصدير البيانات الكبيرة.

حالات الاستخدام الحقيقية لـ HTTP 202

ستواجه 202 Accepted في العديد من التطبيقات الحديثة:

• معالجة الملفات: تحويل ترميز الصور/الفيديو، تحويل المستندات (مثل إنشاء PDF).
• عمليات البيانات: إنشاء تقارير كبيرة، تصدير/استيراد البيانات، إرسال رسائل بريد إلكتروني جماعية.
• الذكاء الاصطناعي/التعلم الآلي: إرسال مهمة لتدريب النموذج أو الاستدلال.
• معالجة الدفع: تقبل بعض بوابات الدفع طلب الدفع بشكل غير متزامن.
• DevOps/CI-CD: تشغيل خط أنابيب البناء. تقبل واجهة برمجة التطبيقات الطلب على الفور وتعيد رابطًا إلى سجلات البناء.

فوائد استخدام 202 Accepted

لماذا يجب على المطورين ومصممي واجهات برمجة التطبيقات استخدام 202؟

1. يمنع انتهاء مهلة العميل: لا يضطر المستخدمون إلى الانتظار.
2. يحسن قابلية التوسع: لا تتعطل الخوادم في المهام الطويلة.
3. ملاحظات أفضل للمستخدم: بدلاً من الصمت، يعرف العملاء أن الطلب قيد المعالجة.
4. يدعم البنى غير المتزامنة: ضروري للخدمات المصغرة الحديثة.

202 Accepted في سير العمل غير المتزامن

إليك كيفية عمله عادةً:

1. يرسل العميل طلبًا.
2. يستجيب الخادم بـ 202 وربما "عنوان URL للحالة".
3. يتحقق العميل مرة أخرى من نقطة نهاية الحالة لمعرفة ما إذا كانت المهمة قد انتهت.

على سبيل المثال:

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

يحافظ هذا النمط على رضا الطرفين: يتلقى العميل إقرارًا فوريًا، ويحصل الخادم على مساحة للتنفس.

اختبار سير عمل 202 باستخدام Apidog

يعد اختبار تدفق API غير المتزامن أكثر تعقيدًا من اختبار استدعاء متزامن بسيط. وهنا يصبح Apidog أداة لا تقدر بثمن.

باستخدام Apidog، يمكنك:

1. برمجة التدفق: إنشاء سيناريو اختبار يرسل طلب POST أولاً ويتحقق من أنه يعيد 202 مع status_url.
2. استخراج المتغيرات: استخدم برمجة Apidog لاستخراج job_id أو status_url تلقائيًا من استجابة 202 وحفظه كمتغير بيئة.
3. اختبار الاستقصاء: إنشاء طلب GET لاحق يستخدم المتغير المستخرج لاستدعاء status_url. يمكنك تكوين Apidog لإعادة محاولة هذا الطلب حتى يحصل على حالة "مكتمل".
4. التحقق من النتيجة النهائية: بمجرد الانتهاء من المهمة، اكتب تأكيدات للتحقق من الاستجابة النهائية من عنوان URL للتنزيل.

يتيح لك ذلك أتمتة اختبار رحلة عدم التزامن بأكملها، مما يضمن الموثوقية واكتشاف الانحدارات.

كيفية اختبار استجابات 202 Accepted (باستخدام Apidog)

هنا يتألق Apidog. على عكس الأدوات الثابتة، يتيح لك Apidog:

• إرسال الطلبات ومحاكاة رموز الحالة المختلفة (مثل 202).
• محاكاة نقاط نهاية API لاختبار سير العمل غير المتزامن.
• توثيق واجهات برمجة التطبيقات حتى يعرف المطورون ما يتوقعونه من استجابة 202.
• التعاون مع أعضاء الفريق لتحسين التعامل غير المتزامن.

باستخدام Apidog، يمكنك بناء واختبار سير عمل 202 من البداية إلى النهاية من القبول إلى الاكتمال دون التبديل بين الأدوات.

المزالق المحتملة وسوء الفهم الشائع

ومع ذلك، يمكن إساءة استخدام 202. تتضمن بعض المزالق ما يلي:

• افتراض الاكتمال: مجرد قبول الطلب لا يعني نجاحه.
• عدم توفير متابعات: يجب أن تتضمن واجهات برمجة التطبيقات طرقًا للعملاء للتحقق من حالة المهمة.
• الإفراط في استخدام 202: لا تستخدمه للعمليات البسيطة والفورية، فسوف يربك العملاء.

التحديات وأفضل الممارسات

يتطلب تطبيق 202 بشكل صحيح تفكيرًا دقيقًا.

1. توفير نقطة نهاية للحالة: هذا غير قابل للتفاوض. يجب عليك توفير عنوان URL (عبر رأس Location أو نص الاستجابة) حيث يمكن للعميل التحقق من تقدم الطلب ونتيجته النهائية.
2. الاستقرار أمر حاسم: إذا لم يكن العميل متأكدًا من أن طلبه قد تم (على سبيل المثال، بسبب مشكلة في الشبكة)، فقد يعيد المحاولة. يجب تصميم واجهة برمجة التطبيقات الخاصة بك للتعامل مع الطلبات المكررة بلطف باستخدام مفاتيح الاستقرار لمنع وضع نفس المهمة في قائمة الانتظار عدة مرات.
3. تحديد توقعات واضحة: استخدم نص الاستجابة لإعطاء وقت تقديري للإنجاز أو رسالة حالة بسيطة (في قائمة الانتظار، قيد المعالجة، فشل، نجح).
4. النظر في Webhooks: كبديل أكثر كفاءة للاستقصاء، اسمح للعملاء بتسجيل عنوان URL لـ webhook الذي سيستدعيه الخادم الخاص بك عند اكتمال المهمة.
5. التخطيط للفشل: قد تفشل المهمة في الخلفية. يجب أن تقوم نقطة نهاية الحالة الخاصة بك بتوصيل حالات الفشل وربما توفير رموز السبب.

أفضل الممارسات لتطبيق 202 Accepted

إذا كنت تصمم واجهات برمجة تطبيقات تعيد 202، فضع هذه الممارسات الأفضل في الاعتبار:

• دائمًا ما تعيد السياق: توفير معرف مهمة أو عنوان URL للحالة.
• توثيق واضح: اشرح كيف يجب على العملاء التحقق من التقدم.
• استخدم webhooks حيثما أمكن: إخطار العملاء عند انتهاء المهام.
• لا تفرط في استخدامه: أعد 202 فقط للمهام غير المتزامنة حقًا.

202 Accepted في واجهات برمجة تطبيقات REST مقابل GraphQL

• واجهات برمجة تطبيقات REST: 202 شائع لأن الطلبات غالبًا ما ترتبط بعمليات طويلة الأمد.
• واجهات برمجة تطبيقات GraphQL: أقل شيوعًا، نظرًا لأن GraphQL تفضل الاستعلامات المتزامنة، ولكن لا يزال ممكنًا مع الطفرات غير المتزامنة.

الخاتمة: تبني التصميم غير المتزامن

رمز حالة HTTP 202 Accepted هو أداة قوية في مجموعة أدوات مصمم واجهة برمجة التطبيقات. إنه يمثل تحولًا من التفكير في واجهات برمجة التطبيقات كآليات بسيطة للطلب والاستجابة إلى التفكير فيها كأنظمة لتنسيق سير العمل المعقدة في العالم الحقيقي. قد لا يكون رمز حالة 202 Accepted هو أشهر رمز HTTP، ولكنه يلعب دورًا حاسمًا في سير عمل واجهة برمجة التطبيقات غير المتزامنة. إنه يخبر العملاء، "لقد تلقينا طلبك، لكننا ما زلنا نعمل عليه."

باستخدام 202، تقوم ببناء واجهات برمجة تطبيقات أكثر قابلية للتوسع، وأكثر مرونة، وتوفر تجربة أفضل بكثير للمطورين الذين يستخدمونها والمستخدمين النهائيين الذين يستفيدون منها في النهاية.

إنه يقر بأن ليس كل شيء في البرامج يحدث على الفور، ويوفر طريقة موحدة وقوية للتعامل مع هذا الواقع.

لذا في المرة القادمة التي تصمم فيها نقطة نهاية لمهمة طويلة الأمد، لا تجبرها على أن تكون متزامنة. احتضن الطبيعة غير المتزامنة للمهمة. أعد 202 Accepted، وقدم عنوان URL للحالة، وحرر تطبيقك من طغيان الطلب المنتظر. إذا كنت تقوم ببناء أو اختبار واجهات برمجة التطبيقات التي تعيد 202، فأنت بحاجة إلى أدوات تتيح لك محاكاة واختبار وتوثيق سير العمل هذه دون عناء. وهذا بالضبط ما يقدمه Apidog. استخدم أداة مثل Apidog لضمان أن تطبيقك قوي وقابل للاختبار وممتع للاندماج معه. هل أنت مستعد لتبسيط اختبار وتوثيق واجهة برمجة التطبيقات الخاصة بك؟ قم بتنزيل Apidog مجانًا اليوم واجعل التعامل مع رموز مثل 202 Accepted أمرًا سهلاً.