201 Created: تأكيد إنشاء مورد جديد

201 Created يؤكد أن الطلب نجح وأنشأ شيئًا جديدًا: حسابًا أو طلب شراء أو ملفًا مرفوعًا أو سجلًا في API. هو رمز خاص بعمليات الكتابة، ويجب أن يشير الرد إلى المورد الجديد.

التعريف

يقول RFC 9110، القسم 15.3.2 إن الطلب «نُفِّذ وأدى إلى إنشاء مورد جديد أو أكثر». ويُعرَّف المورد الرئيسي الجديد بترويسة Location، وإن لم توجد فبرابط الطلب نفسه. وغالبًا يصف الجسم المورد الجديد ويرتبط به. ويأتي الرمز 201 عادةً ردًا على POST (إنشاء داخل مجموعة) أو PUT (إنشاء عند رابط اختاره العميل).

POST /api/v1/articles HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"title":"HTTP status codes for SEO"}

HTTP/1.1 201 Created
Location: /api/v1/articles/4821
Content-Type: application/json

{"id":4821,"title":"HTTP status codes for SEO","status":"draft"}

إذا لم يكتمل العمل بعد فالأصدق أن ترد بـ 202 Accepted. وإذا كان المورد موجودًا مسبقًا ففكّر في 409 Conflict، وإذا فشلت المدخلات في التحقق فـ 422 Unprocessable Content.

التأثير على السيو

ينبغي أن ترد الصفحات المخصصة للبحث على طلبات GET بـ 200 OK وليس 201. وتذكر وثائق Google أن Googlebot مع 201 و202 ينتظر ورود المحتوى لفترة محدودة ثم يمرّر ما استلمه إلى مرحلة الفهرسة. فقد تُعالَج الصفحة المقدَّمة بالرمز 201، لكن هذا الرمز يدل على خطأ في التوجيه أو في الكود، كأن يُعاد استخدام متحكّم (controller) كُتب لإنشاء السجلات في عرض صفحة عامة. أصلح الخطأ ولا تعتمد على تسامح Google.

نصائح للمطورين

• أرسل دائمًا ترويسة Location برابط المورد الجديد.
• أعد التمثيل الذي أُنشئ في الجسم لتوفّر على العميل طلبًا ثانيًا.
• اجعل نقاط الإنشاء آمنة لإعادة المحاولة، مثلًا بمفتاح عدم التكرار (idempotency key)، حتى لا يُنشئ الطلب المكرر نسخًا مكررة.

كيف تتحقق

مرّر الروابط العامة في أداة فحص حالة HTTP؛ وأي رمز غير 200 على صفحة قابلة للفهرسة يستحق المراجعة. وبالنسبة لنقاط API، يطبع curl مع الخيار -i سطر الحالة وترويسة Location:

curl -i -X POST https://api.example.com/v1/articles \
  -H 'Content-Type: application/json' -d '{"title":"Draft"}'

الأسئلة الشائعة