وقت القراءة المقدر : 7 min · تاريخ النشر
اختر المهام قبل العناوين
قائمة الاستخدامات مثل البحث عن منتج أو توافر القراءة أو تحديث السجل أو معالجة التتبع. تحديد الأشخاص المصرح لهم والأنظمة لكل عملية. واجهة برمجة تطبيقات القراءة العامة وواجهة برمجة التطبيقات الإدارية لها متطلبات وصول مختلفة.
قم بإعداد طلب واستجابة لكل مهمة أساسية باستخدام القيم التركيبية والحقول الموضحة. التمييز بين المعرفات والتسميات والوحدات والتواريخ المستقرة. حدد البيانات المفقودة بدلاً من استبدال القيم المعقولة بمعلومات غير معروفة.
حدد تمثيل المعرفات الكبيرة في عقد JSON. باستخدام Number ذي binary64 في JavaScript تقع الأعداد الصحيحة من −9007199254740991 إلى 9007199254740991 ضمن نطاق التشغيل البيني الدقيق في RFC 8259. يمكن تمثيل 9007199254740992 لكنه ليس عددًا صحيحًا آمنًا؛ فالرمز المجاور 9007199254740993 يقرب إلى 9007199254740992 عند فك JSON القياسي في JavaScript.
يحفظ المعرف المكتوب كسلسلة JSON أرقامه. اتفق على النوع بين المنتج والمخطط والمستهلك؛ فتحويل Number مقرب إلى نص لا يستعيد الأصل. قد تحفظ مكتبات أخرى دقة أكبر، لذا اختبر العملاء المدعومين. صحة بنية JSON لا تثبت أمانة القيم ويجب ألا يتغير نوع المعرف بصمت.
مرّر الجدول أفقيًا لقراءة جميع الأعمدة. باستخدام لوحة المفاتيح، انقل التركيز إلى الجدول ثم استخدم مفاتيح الأسهم.
| رمز JSON توضيحي | قيمة JavaScript المعروضة | التفسير |
|---|---|---|
| 9007199254740991 | 9007199254740991 | عدد صحيح آمن في المثال |
| 9007199254740992 | 9007199254740992 | ممثل بدقة لكنه خارج نطاق الأعداد الصحيحة الآمنة |
| 9007199254740993 | 9007199254740992 | قيمة مقربة فقدت الرقم الأخير الأصلي |
| "9007199254740993" | "9007199254740993" | سلسلة دقيقة وفق النوع النصي المتفق عليه |
وصف عقد صريح
يوفر OpenAPI تنسيق وصف مستقل عن اللغة لواجهات برمجة تطبيقات HTTP ، ويغطي العمليات والمعلمات والاستجابات والنماذج. اختر إصدارًا مدعومًا بأدواتك واحتفظ بالمستند مع المشروع ؛ الإصدار الأحدث ليس تلقائيًا مناسبًا لكل سلسلة أدوات.
حدود استخدام المستندات ، ترقيم الصفحات ، المرشحات ، الطلبات ، الأخطاء والإجابات الفارغة. لا تعامل CORS كدليل على الترخيص. مراجعة عمليات التحكم في التشغيل والوصول على مستوى الكائن مع الفريق الفني.
لواجهة API افتراضية لمعالجة الطلبات، صف الاستجابات الأربع أدناه بصورة منفصلة. في هذا الاتفاق، يعيد 201 موردًا منشأً مع الترويسة Location؛ ويقدم 202 مرجع متابعة لأن العمل لم ينتهِ. لا تحوّل جميع استجابات 2xx إلى رسالة «اكتملت العملية». على العميل قراءة الحالة والترويسات والنموذج المحدد للعملية.
لا تحتوي استجابة 204 على متن لفك ترميزه بصيغة JSON. في هذا المثال تتلقى تعليمة صحيحة نحويًا لكنها تخالف قاعدة عمل الحالة 422 مع مشكلة منظمة بصيغة application/problem+json. إذا وُجد العضو status، فعلى الجهة المولّدة مطابقته مع حالة HTTP الفعلية؛ ولا ينبغي للنص المترجم في detail أن يصبح مفتاح قرار البرنامج. وثّق معرّفات المشكلة الثابتة وإجراء التصحيح المتوقع.
مرّر الجدول أفقيًا لقراءة جميع الأعمدة. باستخدام لوحة المفاتيح، انقل التركيز إلى الجدول ثم استخدم مفاتيح الأسهم.
| الاستجابة المقررة | الحقيقة المثبتة | فحص المستهلك |
|---|---|---|
| 201 | أُنشئ المورد | فحص Location المطلوب بهذا الاتفاق ومعرّف المورد |
| 202 | قُبلت المعالجة ولم تكتمل | حفظ مرجع المتابعة وانتظار النتيجة النهائية |
| 204 | نجح الإجراء دون متن استجابة | عدم محاولة فك متن فارغ بصيغة JSON |
| 422 | التعليمة مفهومة لكن القاعدة تمنع معالجتها | قراءة المشكلة المنظمة واقتراح التصحيح المناسب |
- RFC 9110 : HTTP Semantics
RFC 9110، تمت مراجعتها في 22 أكتوبر 2026: دلالات الحالات. الاستجابات والحقول المطلوبة هنا اتفاق افتراضي.
- RFC 9457 : Problem Details
RFC 9457، تمت مراجعتها في 22 أكتوبر 2026: صيغة المشكلات ودور العضو status.
منع تعديل من الكتابة فوق تعديل محرّر آخر
- قراءتان للنسخة r7
- الكتابة الأولى: r8
- الكتابة القديمة: 412
- قارن قبل المتابعة
سيناريو افتراضي: يفتح محرّران السجل DEMO-17 مع ETag قوي قيمته "r7". يحفظ الأول تصحيحًا فتصبح النسخة الحالية "r8"، بينما لا يزال الثاني يعمل على "r7". يمكن للكتابة المشروطة كشف هذا الاختلاف قبل استبدال النسخة المنشورة.
في واجهة API تدعم هذا العقد، يرسل العميل If-Match مع أداة التحقق القوية التي تلقّاها. يقارن الخادم النسخة قبل الكتابة؛ ويحدّد المثال الاستجابة 412 عند تغيّرها. القيمة W/"r7" ضعيفة ولا تحقق المقارنة القوية. أما If-Match: * فيتحقق من وجود تمثيل حالي، لا من بقائه دون تغيير منذ قراءته.
احتفظ بمسودة المحرّر الثاني واقرأ النسخة الحالية واعرض الفروق قبل اتخاذ قرار جديد. استبدال أداة التحقق تلقائيًا بـ "r8" ثم إعادة إرسال المسودة القديمة يتجاوز الحماية. يجب أن يكون التحقق والكتابة عملية غير قابلة للتجزئة في التخزين؛ فلا يكتب طلبان متزامنان يحملان الأداة نفسها كلاهما فوق النسخة نفسها.
هذا التحكم في التزامن لا يغني عن المصادقة أو صلاحيات السجل أو التحقق من الحقول. ولا يضمن تنفيذ استدعاء خارجي مرة واحدة. اختبر هذه الخصائص منفصلة ووثّق حالة غياب الشرط المسبق؛ يمكن استخدام 428 لاشتراط طلب مشروط.
مرّر الجدول أفقيًا لقراءة جميع الأعمدة. باستخدام لوحة المفاتيح، انقل التركيز إلى الجدول ثم استخدم مفاتيح الأسهم.
| الخطوة | النسخة والطلب | النتيجة المتوقعة وفق العقد |
|---|---|---|
| قراءة المحرّرين | ETag: "r7" | يحتفظ كل منهما بأداة التحقق مع مسودته. |
| الحفظ الأول | If-Match: "r7" → النسخة "r8" | يُحفظ تصحيح المحرّر الأول. |
| الحفظ الثاني بنسخة قديمة | If-Match: "r7"؛ النسخة الحالية "r8" | 412؛ لا تستبدل التصحيح المحفوظ. |
| مقارنة صريحة | اقرأ "r8" ثم قارن واتخذ القرار | احتفظ بالمسودة وافحص الصلاحيات قبل أي كتابة جديدة. |
- IETF · RFC 9110 § 13.1.1
IETF : الكتابة المشروطة والشروط المسبقة
- IETF · RFC 6585 § 3
428 · Precondition Required
اختبار الحدود والأذونات
جرب كائنًا موجودًا وكائنًا مفقودًا ومعلمة غير صالحة وقائمة أطول من صفحة واحدة. تحقق من الصفحة التالية بحثًا عن الخسائر أو التكرارات داخل نموذج التحديث المختار. تفرض قيودًا على أن واجهة برمجة التطبيقات لا يمكن أن تضمنها.
استخدم حسابات الاختبار بأذونات مختلفة. محاولة القراءات والتغييرات خارج النطاق المسموح به باستخدام البيانات التركيبية. سجل الحالات المتوقعة والرسائل المفيدة دون الكشف عن الآثار الداخلية أو أسرار التكوين.
خطة التغيير والدعم
تميز حقلًا مضافًا من حقل تمت إزالته أو معنى متغير. تحديد المستهلكين قبل تغيير غير متوافق. اشرح الفترة الانتقالية وكيفية اكتشاف عمليات التكامل التي لا تزال تستخدم العقد السابق.
تقديم مثال قابل للتنفيذ لبيئة اختبار ومصفوفة اختبار واتصال تقني. اربط الأخطاء الملحوظة بأمثلة موثقة بعد الإصدار. الوثائق التي تقتصر على الحالة المثالية تترك المتكاملين دون توجيه للرفض والانقطاعات.
التوثيق الأساسي: مبادرة OpenAPI - المواصفات.
المستندات المرجعية
- مبادرة OpenAPI - المواصفات · مصدر تمت مراجعته
- IETF : RFC 8259: JSON numbers · مصدر تمت مراجعته
- TC39 : Number.isSafeInteger · مصدر تمت مراجعته
تاريخ تحديث المحتوى
مراجع موثقة لهذا الموضوع
| المرجع | القيمة أو الصيغة | النطاق |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | لا يسمح JSON القياسي بالتعليقات أو الفاصلة الختامية؛ وتستخدم السلاسل علامات اقتباس مزدوجة. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | يربط فرق التوقيت الصريح الوقت المحلي بـUTC؛ هذا المثال ليس موعدًا. |
| HTTP · If-Match | If-Match: "r7" → 412 | يقارن If-Match أداة تحقق قوية قبل الكتابة. وفق العقد الموضح، تتلقى النسخة القديمة 412؛ وتُحفظ المسودة لمقارنة التعديلات. |
| HTTP · 428 | 428 · Precondition Required | يتيح 428 للخادم اشتراط طلب مشروط. ينبغي توثيق استخدامه في العقد؛ فالحالة لا توفّر قفلًا بحد ذاتها. |
تشير التواريخ إلى الاطلاع على المراجع. هذه المعلومات ليست تدقيقاً للموقع ولا إعلاناً شاملاً عن المطابقة.
