بحث
أدخل حرفين على الأقل دون بيانات شخصية.

    مكتبةالمقالات والأسئلة الشائعة مشروعكطلب عرض أسعار
    لغةAR ▾
    أدلة عملية

    توثيق واختبار واجهة برمجة التطبيقات من حالات الاستخدام الخاصة بها

    تتيح واجهة برمجة التطبيقات المفيدة لفريق آخر فهم ما يمكنه طلبه وما سيحصل عليه. يجب أن يكون عقدها قابلاً للاختبار وإصداره ومتوافقًا مع خدمة التشغيل.

    انظر الطريقة

    صورة توضيحية — توثيق واختبار واجهة برمجة التطبيقات من حالات الاستخدام الخاصة بها
    رسم توضيحي مولّد بالذكاء الاصطناعي

    اختر المهام قبل العناوين

    يقرب ⁦JavaScript⁩ العدد ⁦9007199254740993⁩ بينما تحفظ السلسلة أرقامها.
    صورة توضيحية · توضيح ⁦JSON.parse⁩: يقرب ⁦Number⁩ الرمز العددي هنا وتحفظ ⁦String⁩ الأرقام. اتفق على التمثيل النصي قبل التحويل.

    قائمة الاستخدامات مثل البحث عن منتج أو توافر القراءة أو تحديث السجل أو معالجة التتبع. تحديد الأشخاص المصرح لهم والأنظمة لكل عملية. واجهة برمجة تطبيقات القراءة العامة وواجهة برمجة التطبيقات الإدارية لها متطلبات وصول مختلفة.

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

    حدد تمثيل المعرفات الكبيرة في عقد ⁦JSON.⁩ باستخدام ⁦Number⁩ ذي ⁦binary64⁩ في ⁦JavaScript⁩ تقع الأعداد الصحيحة من ⁦−9007199254740991⁩ إلى ⁦9007199254740991⁩ ضمن نطاق التشغيل البيني الدقيق في ⁦RFC⁩ ⁦8259.⁩ يمكن تمثيل ⁦9007199254740992⁩ لكنه ليس عددًا صحيحًا آمنًا؛ فالرمز المجاور ⁦9007199254740993⁩ يقرب إلى ⁦9007199254740992⁩ عند فك ⁦JSON⁩ القياسي في ⁦JavaScript.⁩

    يحفظ المعرف المكتوب كسلسلة ⁦JSON⁩ أرقامه. اتفق على النوع بين المنتج والمخطط والمستهلك؛ فتحويل ⁦Number⁩ مقرب إلى نص لا يستعيد الأصل. قد تحفظ مكتبات أخرى دقة أكبر، لذا اختبر العملاء المدعومين. صحة بنية ⁦JSON⁩ لا تثبت أمانة القيم ويجب ألا يتغير نوع المعرف بصمت.

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

    فك ⁦JSON⁩ القياسي في ⁦JavaScript⁩: الدقة والنوع
    رمز ⁦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 أن يصبح مفتاح قرار البرنامج. وثّق معرّفات المشكلة الثابتة وإجراء التصحيح المتوقع.

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

    أربع استجابات لواجهة API افتراضية وآثارها على العميل
    الاستجابة المقررةالحقيقة المثبتةفحص المستهلك
    201أُنشئ الموردفحص Location المطلوب بهذا الاتفاق ومعرّف المورد
    202قُبلت المعالجة ولم تكتملحفظ مرجع المتابعة وانتظار النتيجة النهائية
    204نجح الإجراء دون متن استجابةعدم محاولة فك متن فارغ بصيغة JSON
    422التعليمة مفهومة لكن القاعدة تمنع معالجتهاقراءة المشكلة المنظمة واقتراح التصحيح المناسب
    • RFC 9110 : HTTP Semantics

      RFC 9110، تمت مراجعتها في 22 أكتوبر 2026: دلالات الحالات. الاستجابات والحقول المطلوبة هنا اتفاق افتراضي.

    • RFC 9457 : Problem Details

      RFC 9457، تمت مراجعتها في 22 أكتوبر 2026: صيغة المشكلات ودور العضو status.

    منع تعديل من الكتابة فوق تعديل محرّر آخر

    1. قراءتان للنسخة r7
    2. الكتابة الأولى: r8
    3. الكتابة القديمة: 412
    4. قارن قبل المتابعة

    سيناريو افتراضي: يفتح محرّران السجل 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" ثم قارن واتخذ القراراحتفظ بالمسودة وافحص الصلاحيات قبل أي كتابة جديدة.

    اختبار الحدود والأذونات

    جرب كائنًا موجودًا وكائنًا مفقودًا ومعلمة غير صالحة وقائمة أطول من صفحة واحدة. تحقق من الصفحة التالية بحثًا عن الخسائر أو التكرارات داخل نموذج التحديث المختار. تفرض قيودًا على أن واجهة برمجة التطبيقات لا يمكن أن تضمنها.

    استخدم حسابات الاختبار بأذونات مختلفة. محاولة القراءات والتغييرات خارج النطاق المسموح به باستخدام البيانات التركيبية. سجل الحالات المتوقعة والرسائل المفيدة دون الكشف عن الآثار الداخلية أو أسرار التكوين.

    خطة التغيير والدعم

    تميز حقلًا مضافًا من حقل تمت إزالته أو معنى متغير. تحديد المستهلكين قبل تغيير غير متوافق. اشرح الفترة الانتقالية وكيفية اكتشاف عمليات التكامل التي لا تزال تستخدم العقد السابق.

    تقديم مثال قابل للتنفيذ لبيئة اختبار ومصفوفة اختبار واتصال تقني. اربط الأخطاء الملحوظة بأمثلة موثقة بعد الإصدار. الوثائق التي تقتصر على الحالة المثالية تترك المتكاملين دون توجيه للرفض والانقطاعات.

    التوثيق الأساسي: مبادرة OpenAPI - المواصفات.

    المستندات المرجعية

    تاريخ تحديث المحتوى

    مراجع موثقة لهذا الموضوع

    مراجع موثقة لهذا الموضوع
    المرجعالقيمة أو الصيغةالنطاق
    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 للخادم اشتراط طلب مشروط. ينبغي توثيق استخدامه في العقد؛ فالحالة لا توفّر قفلًا بحد ذاتها.

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

    ميّز حالة HTTP وJSON ونتيجة العمل

    اختر تبادلًا افتراضيًا وجرّب قراءته محليًا. نجاح HTTP وقراءة JSON واكتمال العملية فحوص منفصلة.

    المقتطفات غير مكتملة وتستخدم عناوين تجريبية. ينشئ الاختبار Response في الذاكرة: لا يتصل بخادم ولا يحاكي الشبكة أو الذاكرة المؤقتة أو معالجة العمل.

    200تمثيل كامل جديد
    المعنى
    في المقتطف يجيب الخادم عن GET مشروط بجسم JSON ومدقّق demo-v2.
    ما يجب فحصه
    قارن If-None-Match وETag وإصدار الجسم. يقرأ الاختبار المحلي JSON المقدم في المثال.
    نقطة انتباه
    الحالة 200 لا تضمن JSON صالحًا أو بيانات عمل صحيحة. نجاح القراءة هنا لا يعتمد مخطط بياناتك.
    مقتطف تبادل افتراضي
    GET /demo/catalogue
    If-None-Match: "demo-v1"
    
    HTTP/1.1 200 OK
    ETag: "demo-v2"
    Content-Type: application/json
    
    {"revision":"demo-v2"}

    202مقبول والمعالجة ما تزال معلّقة
    المعنى
    تشير 202 إلى قبول الطلب للمعالجة لا إلى اكتمالها. يعرض الجسم الافتراضي queued.
    ما يجب فحصه
    احتفظ بالمرجع DEMO-42 وتابع حالته وفق عقد API وصلاحيات الوصول وحدود إعادة المحاولة.
    نقطة انتباه
    قيمة Response.ok هي true. لا تثبت هذه القيمة أو قابلية قراءة JSON اكتمال المعالجة. الحقول وعنوان المتابعة اتفاقات افتراضية في المثال.
    مقتطف تبادل افتراضي
    POST /demo/jobs
    
    HTTP/1.1 202 Accepted
    Location: /demo/jobs/DEMO-42
    Content-Type: application/json
    
    {"job":"DEMO-42","status":"queued"}

    204نُفّذ الطلب دون جسم استجابة
    المعنى
    تشير 204 إلى تنفيذ الخادم للطلب دون محتوى استجابة. لا ينقل المقتطف JSON.
    ما يجب فحصه
    عالج غياب الجسم وفق العقد. تحقّق مما تؤكده نقطة الاستقبال قبل إعلان نتيجة للزائر.
    نقطة انتباه
    تفشل قراءة الجسم الفارغ بوصفه JSON رغم أن Response.ok هي true. قد يؤكد webhook الاستلام فقط؛ وتبقى إجراءات العمل اللاحقة بحاجة إلى تحقق.
    مقتطف تبادل افتراضي
    POST /demo/events
    
    HTTP/1.1 204 No Content

    304أُعيد التحقق من النسخة دون جسم جديد
    المعنى
    تجيب 304 عن طلب مشروط: يمكن إعادة استخدام التمثيل المحفوظ. لا تقدم جسمًا جديدًا.
    ما يجب فحصه
    قارن المدقّق المُرسل بالنسخة demo-v2 المتاحة. يعتمد التفسير أيضًا على النسخة المحفوظة.
    نقطة انتباه
    ينشئ الاختبار Response 304 منفردة، لا ذاكرة HTTP مؤقتة. في fetch فعلي قد يقدم المتصفح الاستجابة المحفوظة، فيختلف رمز الشبكة عن الرمز المتاح للبرنامج.
    مقتطف تبادل افتراضي
    GET /demo/catalogue
    If-None-Match: "demo-v2"
    
    HTTP/1.1 304 Not Modified
    ETag: "demo-v2"

    مراجع تقنية : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

    مصفوفة التحقق الوظيفي للتكيف مع المشروع

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

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

    حالات الاختبار والنتائج المتوقعة والأدلة المفيدة
    قضيةنتيجة متوقعةدليل على الاحتفاظ بها
    الموارد الحالية والغائبةتتطابق كل نتيجة مع الحالة الموثقة ونموذج الاستجابة.الطلب والاستجابة ومثال العقد المقابل الذي تم التقاطه من بيئة الاختبار.
    معلمة خارج النطاقالرفض مفهوم ولا يفضح أي تتبع داخلي للمكدس.الرسالة العامة والنتيجة المحتفظ بها في مصفوفة القبول.
    مستويين إذنيظل المورد المحظور غير قابل للوصول حتى مع معرف معروف.مقارنة النتائج باستخدام حسابين اصطناعيين بأذونات مختلفة بشكل صريح.
    ترقيم الصفحات والفلتر المتغيريتم تحديد التعامل مع الرمز المميز وسلوك إعادة تشغيل الرحلة.الطلب والمعرفات والقواعد المرتجعة التي يتم تطبيقها عند تغيير الفلتر.

    أسئلة مكررة

    هل تم إنشاء التوثيق بما يكفي لاختبار واجهة برمجة التطبيقات؟

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

    هل تحل CORS محل أذونات الوصول؟

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

    موضوعات مرتبطة