تفتح تطبيق التوصيل على جوالك فيظهر لك أن طلبك خرج من المطعم وأن المندوب على بعد كيلومترين، وتفتح تطبيق البنك فيظهر رصيدك، وتضغط «ادفع» في متجر إلكتروني فتظهر صفحة بوابة الدفع ثم تعود إلى المتجر برسالة نجاح. ولا شيء من هذه البيانات موجود في جوالك، فالتطبيق في كل مرة يرسل رسالة قصيرة إلى برنامج آخر على سيرفر بعيد، ويستقبل رداً، ويعرضه. وهذه الرسائل لها شكل متفق عليه بين الطرفين بدقة، فلو أرسل التطبيق اسم حقل خطأ أو فهم رقماً بطريقة مختلفة لظهر لك رصيد غير صحيح أو حجز لم تطلبه. وهذا الاتفاق هو ما يسمى واجهة برمجة التطبيقات Application Programming Interface، واختصاراً API.
وإذا كنت مطوراً فسوف تقف على طرفي هذا الاتفاق قريباً: مرة تكتب API يستخدمه تطبيق الجوال أو فريق آخر، ومرة تستخدم API لبوابة دفع أو خدمة رسائل أو خريطة. وفي الحالتين تحتاج أن تعرف الأساسيات نفسها: ما الذي يتكون منه الطلب والرد، وكيف تكتب البيانات بصيغة JSON دون أن يضيع منها شيء، وماذا يقول لك كل رمز حالة Status Code، وما الذي يجب أن يفعله الكلاينت عند كل خطأ. وقد شرحنا بروتوكول HTTP نفسه في مقال HTTP وHTTPS، وشرحنا كيف تصمم API يبقى متوافقاً مع عملائه لسنوات في مقال تصميم الواجهات، وهذا المقال هو الخطوة التي بينهما: ال API من أول طلب إلى أول خطأ، على واجهة صغيرة حقيقية نشغلها ونرسل إليها الطلبات ونقرأ ردودها سطراً سطراً.
وسوف نناقش في هذا المقال ما يلي:
- ما هي ال API، ولماذا هي عقد Contract بين برنامجين، وأنواعها من مكتبة في نفس البرنامج إلى خدمة على الإنترنت.
- مم يتكون الطلب Request والاستجابة Response في Web API، والطرق Methods التي تقول ماذا تريد.
- صيغة JSON: الأنواع، والنص العربي، والأرقام الكبيرة التي تفقد خاناتها، والمبالغ المالية، والتواريخ.
- رموز الحالة Status Codes من زاوية الكلاينت: من المخطئ، وهل يعيد المحاولة.
- تجربة عملية على واجهة فعاليات صغيرة بلغة Python وFastAPI: نصنع الأخطاء 400 و401 و403 و404 و405 و409 و422 و500 بأنفسنا، ونرى ثلاث مشاكل حقيقية ظهرت في الطريق.
- أساسيات إعادة المحاولة الآمنة Idempotency، والتقسيم إلى صفحات Pagination، والإصدارات Versioning، وملف OpenAPI الذي تولده الأداة، وما الذي ينقصه.
ما هي واجهة API؟
ال API هي الطريقة المتفق عليها التي يطلب بها برنامج خدمة من برنامج آخر دون أن يعرف كيف يعمل من الداخل. والتشبيه القريب هو شباك الخدمة في جهة حكومية: أنت لا تدخل إلى المكاتب ولا تعرف من يعالج طلبك ولا أين تحفظ الملفات، وإنما تعرف أن الشباك رقم 3 يستقبل نموذجاً محدداً فيه حقول محددة، وأنك تحصل في المقابل على رقم معاملة، أو على ورقة تقول لك لماذا رفض طلبك. فإذا غيرت الجهة طريقة عملها في الداخل فلن تتأثر ما دام النموذج والرد كما هما، وإذا غيرت النموذج نفسه دون أن تخبرك فسوف يرفض طلبك غداً.
والكلمة نفسها أقدم من الإنترنت، وتستخدم لثلاثة أشياء على الأقل:
- واجهة مكتبة Library API: الدوال والكلاسات التي تعرضها مكتبة لمن يستخدمها، مثل الدالة
json.loadsفي Python، فاسمها ومعاملاتها وما تعيده هي العقد. - واجهة نظام التشغيل OS API: الاستدعاءات التي يطلب بها برنامجك من النظام أن يفتح ملفاً أو يرسل عبر الشبكة، مثل
openوreadفي Linux. - واجهة الويب Web API: برنامج على سيرفر يستقبل طلبات عبر HTTP ويرد عليها، غالباً بصيغة JSON، وهي ما يقصده أغلب المطورين اليوم بكلمة API، وهي موضوع هذا المقال.
ال API عقد Contract: ما الذي يتفق عليه الطرفان؟
أهم فكرة في هذا المقال كله أن ال API عقد، وأن الكود خلفه تفصيل. والعقد في Web API يحدد ما يلي:
- العنوان Endpoint: الرابط الذي ترسل إليه، مثل
/v1/events/2/registrations. - الطريقة Method: ماذا تريد أن تفعل، قراءة أم إنشاء أم حذف.
- المدخلات Inputs: المعاملات في الرابط، والترويسات Headers، وجسم الطلب Body بحقوله وأنواعها، وما هو إلزامي منها.
- المخرجات Outputs: شكل الرد عند النجاح، ورمز الحالة الذي يصاحبه.
- الأخطاء Errors: ما الأخطاء الممكنة، ورمز كل منها، وشكل رسالته.
- المصادقة Authentication والحدود Limits: كيف تثبت من أنت، وكم طلباً يسمح لك في الدقيقة.
والسبب في أن العقد أهم من الكود أن الطرف الآخر لا يرى كودك، وإنما يبني تطبيقه على ما رآه في الرد، فإذا كان الرد يعيد السعر كرقم ثم صار يعيده كنص، أو كان الخطأ 404 ثم صار 400، فقد عطلت تطبيقاً لا تعرف عنه شيئاً، حتى لو كان التغيير في كودك «تحسيناً». ولذلك تكتب الفرق المحترفة العقد في ملف OpenAPI كما سوف نرى، وتعامله كجزء من الكود يراجع ويختبر.
وفي سنة 2000 وصف Roy Fielding في الفصل الخامس من رسالة الدكتوراه أسلوباً معمارياً سماه REST، يقوم على موارد Resources لها عناوين، وطرق قياسية للتعامل معها، وردود لا تعتمد على حالة محفوظة في السيرفر بين الطلبات، وأصبح هذا الأسلوب هو الشكل الأشهر لواجهات الويب. وهناك أساليب أخرى مثل gRPC وGraphQL قارناها في مقال تصميم الواجهات، ولكن الأساسيات في هذا المقال مشتركة بينها كلها.
الطلب Request والاستجابة Response: رسالتان نصيتان
كل تعامل مع Web API رسالتان: طلب يرسله الكلاينت، واستجابة يرسلها السيرفر. والطلب يتكون من أربعة أجزاء:
- الطريقة Method، مثل
POST. - العنوان URL، وفيه عنوان السيرفر Base URL، ثم رقم الإصدار
v1، ثم الموردevents، ثم معامل المسار Path Parameter مثل رقم الفعالية2، وقد يكون بعده معاملات الاستعلام Query Parameters بعد علامة الاستفهام مثل?limit=2&offset=2. - الترويسات Headers: معلومات عن الطلب نفسه، مثل نوع المحتوى
Content-Type: application/json، والتوكن فيAuthorization: Bearer .... - الجسم Body: البيانات نفسها، وتوجد غالباً في POST وPUT وPATCH فقط.
والاستجابة تتكون من ثلاثة أجزاء: سطر الحالة وفيه رمز الحالة مثل 201 Created، ثم الترويسات مثل Location الذي يقول أين المورد الجديد، ثم الجسم. والصورة التالية تبين طلباً حقيقياً من التجربة ورده:

الطرق Methods: ماذا تريد أن تفعل؟
الطرق في HTTP كثيرة، وفي ال API تستخدم خمس منها غالباً، ولكل منها صفتان يحددهما المعيار RFC 9110 ويعتمد عليهما كل من في الطريق، من المتصفح إلى ال Proxy إلى مكتبة الكلاينت: الآمنة Safe، أي أنها لا تغير شيئاً في السيرفر، والقابلة للتكرار Idempotent، أي أن إرسالها مرتين يترك نفس الأثر في السيرفر كإرسالها مرة:
| الطريقة | الاستخدام المعتاد | آمنة Safe | قابلة للتكرار Idempotent |
|---|---|---|---|
GET | قراءة مورد أو قائمة | نعم | نعم |
POST | إنشاء مورد جديد، أو تنفيذ عملية | لا | لا |
PUT | استبدال المورد كاملاً بما في الجسم | لا | نعم |
PATCH | تعديل حقول محددة في المورد | لا | ليس بالضرورة |
DELETE | حذف المورد | لا | نعم |
وهذا الجدول ليس نظرياً، فمكتبات الكلاينت وال Proxies تعيد إرسال الطلبات القابلة للتكرار تلقائياً عند انقطاع الاتصال، وتمتنع عن إعادة POST، لأن إعادة POST قد تنشئ مورداً ثانياً. لذلك لا تقم باستخدام GET لعملية تغير شيئاً، مثل رابط GET /delete?id=5، والسبب أن أي أداة تفتح الروابط مسبقاً أو تعيد المحاولة سوف تنفذ الحذف دون أن يقصده أحد. وتفاصيل الطرق كلها في مقال HTTP.
الترويسات Headers التي تحتاجها في كل API
الترويسات هي المكان الذي يضع فيه الطرفان معلومات عن الرسالة نفسها وليس عن بياناتها، وأغلب ال APIs تحتاج القائمة التالية، وما عداها تجده في مقال HTTP:
Content-Type: نوع الجسم الذي أرسلته، وفي ال API غالباًapplication/json. والكلاينت يرسلها مع الطلب، والسيرفر مع الرد، فإذا أرسلت JSON دون هذه الترويسة فقد يرفضه السيرفر أو يقرؤه كنص عادي.Accept: الأنواع التي يقبلها الكلاينت في الرد، وهي أساس التفاوض على المحتوى Content Negotiation، مثل أن يطلب الكلاينت CSV بدلاً من JSON من نفس العنوان.Authorization: إثبات الهوية، وأشهر أشكالهBearerثم التوكن، وقد شرحنا التوكنات والجلسات في مقال الجلسات وJWT.Location: في رد الإنشاء 201، عنوان المورد الجديد.Retry-After: مع 429 و503، كم ثانية ينتظر الكلاينت قبل أن يعيد.ETagوIf-None-Match: بصمة لنسخة المورد، يرسلها الكلاينت في الطلب التالي فيرد السيرفر 304 دون جسم إذا لم يتغير شيء، فيوفر نقل البيانات.Idempotency-Key: مفتاح يجعل إعادة POST آمنة، وسوف نجربه في التجربة.- معرف الطلب Request ID: ترويسة مثل
X-Request-IDيضيفها السيرفر أو ال Reverse Proxy لكل طلب، وتظهر في السجل، فإذا اشتكى مستخدم أرسل لك هذا المعرف ووجدت طلبه بالضبط.
وإذا كان ال API يستدعى من صفحة ويب على نطاق آخر، فهناك ترويسات CORS التي يطلبها المتصفح قبل أن يسمح للصفحة بقراءة الرد، وقد خصصنا لها مقالاً كاملاً لأنها أكثر ما يحير المطورين في أول API يكتبونه.
JSON: اللغة التي تتكلم بها أغلب ال APIs
JSON صيغة نصية لتمثيل البيانات عرفها المعيار RFC 8259، ولها ستة أنواع فقط: الكائن Object بين قوسين معقوفين، والمصفوفة Array بين قوسين مربعين، والنص String بين علامتي تنصيص مزدوجتين، والرقم Number، والقيمتان true وfalse، والقيمة null. وبساطة الصيغة هي سبب انتشارها، فكل لغة تقرؤها وتكتبها، ولكن البساطة نفسها تعني أن أشياء كثيرة غير موجودة فيها، وعليك أنت وعقدك أن تحددها:
- لا يوجد نوع للتاريخ: يكتب التاريخ كنص، والصيغة المتفق عليها هي RFC 3339، أي ISO 8601 مع المنطقة الزمنية، مثل
"2026-12-03T16:00:00Z"حيث الحرف Z يعني توقيت UTC. ولا تقم بإرسال"03/12/2026"، لأن نصف العالم يقرؤه الثالث من ديسمبر والنصف الآخر الثاني عشر من مارس. - الرقم في JSON ليس له حد، ولكن الرقم في اللغة التي تقرؤه له حد: JavaScript تحفظ كل الأرقام كأعداد عشرية بدقة 64 بت، فأكبر عدد صحيح تحفظه بدقة هو 2 أس 53 ناقص 1، وهو Number.MAX_SAFE_INTEGER، والمعيار نفسه في القسم السادس ينبه إلى أن الأعداد خارج هذا المدى لا يمكن الاعتماد على تبادلها. لذلك المعرفات الكبيرة ترسل كنص، وسوف نرى ماذا يحدث إذا لم تفعل.
- المبالغ المالية: الأعداد العشرية بالفاصلة العائمة لا تمثل 0.1 بدقة، فلا ترسل المبلغ كـ
150.1، وإنما كنص"150.10"أو كعدد صحيح بالهللة15010، واذكر العملة. - النص العربي: المعيار يلزم الترميز UTF-8 لكل JSON يتبادل بين الأنظمة، فالنص العربي يرسل كما هو، وبعض المكتبات تكتبه بالشكل
لقاء، وهو صحيح أيضاً ويقرأ بنفس النتيجة، ولكنه أكبر حجماً وأصعب قراءة في السجلات. - الفرق بين
nullوالحقل الغائب: في التعديل الجزئي PATCH، الحقل الغائب يعني «لا تغيره» وnullيعني «امسح قيمته»، فحدد في العقد ما يعنيه كل منهما. - أسماء الحقول: اختر طريقة واحدة،
starts_atأوstartsAt، والتزم بها في كل ال API.

رموز الحالة Status Codes: من المخطئ، وماذا يفعل الكلاينت؟
رمز الحالة ثلاثة أرقام، والرقم الأول يقول الكثير وحده: 2xx نجح الطلب، و3xx اذهب إلى مكان آخر، و4xx الخطأ في طلبك أنت، و5xx الخطأ في السيرفر. وأهم ما يجب أن يفهمه الكلاينت من الرمز سؤالان: هل الخطأ مني أم من السيرفر؟ وهل إعادة الطلب نفسه قد تنجح؟ فخطأ 4xx لن يصلحه التكرار، لأن الطلب نفسه هو المشكلة، ويحتاج تغييراً في المدخلات أو في التوكن، أما 5xx وانقطاع الاتصال فقد يصلحهما التكرار بعد قليل، والاستثناء الأشهر هو 429 الذي يعني «أرسلت كثيراً، انتظر» ومعه عادة الترويسة Retry-After. والجدول التالي يجمع الرموز التي سوف نصنعها في التجربة:
| الرمز | المعنى | من المخطئ | ماذا يفعل الكلاينت |
|---|---|---|---|
| 200 OK | نجح الطلب، والرد في الجسم | لا أحد | يقرأ الجسم |
| 201 Created | أنشئ مورد جديد، وعنوانه في Location | لا أحد | يحفظ المعرف أو العنوان |
| 204 No Content | نجح الطلب ولا يوجد جسم | لا أحد | لا يحاول قراءة JSON |
| 400 Bad Request | الطلب نفسه غير مفهوم، مثل JSON صيغته غير صالحة | الكلاينت | يصلح الكود الذي يبني الطلب |
| 401 Unauthorized | لا نعرف من أنت: لا يوجد توكن أو التوكن غير صالح | الكلاينت | يسجل الدخول أو يجدد التوكن |
| 403 Forbidden | نعرف من أنت، وليس مسموحاً لك | الكلاينت | يعرض رسالة، ولا يعيد المحاولة |
| 404 Not Found | المورد غير موجود | الكلاينت | يعرض «غير موجود» |
| 405 Method Not Allowed | العنوان موجود، والطريقة غير مدعومة، والمسموح في Allow | الكلاينت | يصلح الطريقة |
| 409 Conflict | الطلب صحيح ولكنه يتعارض مع حالة المورد، مثل تسجيل مكرر أو فعالية ممتلئة | الحالة الحالية | يعرض السبب للمستخدم |
| 422 Unprocessable Content | الصيغة صحيحة والحقول لا تحقق القواعد | الكلاينت | يعرض الأخطاء بجانب الحقول |
| 500 Internal Server Error | خطأ غير متوقع في كود السيرفر | السيرفر | يعيد المحاولة لاحقاً إذا كانت الطريقة قابلة للتكرار |
وأكثر خلط يحدث بين 401 و403: الأول يعني «من أنت؟» والثاني يعني «عرفتك، ولا يسمح لك». واسم 401 في المعيار Unauthorized مضلل قليلاً لأنه عن المصادقة Authentication وليس التفويض Authorization، وقد شرحنا الفرق بينهما في مقال المصادقة والتفويض. والصورة التالية تحول الجدول إلى أسئلة يسألها الكلاينت عند كل رد:

شكل رسالة الخطأ Error Format: واحد في كل ال API
رمز الحالة يقول نوع الخطأ، ولكن المستخدم يحتاج أن يعرف ماذا يصلح، لذلك يحمل جسم الرد رسالة الخطأ، والقاعدة الأهم أن يكون شكلها واحداً في كل ال API، فالكلاينت يكتب دالة واحدة تقرأ كل الأخطاء. وهناك معيار لهذا الشكل اسمه Problem Details، وآخر إصداراته RFC 9457، ويعرف حقولاً مثل type وtitle وstatus وdetail، مع نوع المحتوى application/problem+json، وقد طبقناه في مقال تصميم الواجهات. وفي التجربة سوف نستخدم الشكل الافتراضي في FastAPI، أي الحقل detail، لأنه يكفي لرؤية المفاهيم، ولكن لاحظ أن هذا الحقل نص في بعض الأخطاء وقائمة في غيرها، وهذا بالضبط ما يجعل كود الكلاينت أصعب، ولذلك تختار أغلب الفرق شكلاً موحداً منذ أول Endpoint.
التحقق Validation: لماذا يتحقق السيرفر حتى لو تحقق الكلاينت؟
تطبيق الجوال يتحقق من البريد قبل أن يرسله، فلماذا يتحقق السيرفر مرة أخرى؟ والإجابة أن السيرفر لا يعرف من أرسل الطلب فعلاً، فقد يكون التطبيق الرسمي، أو نسخة قديمة منه لا تعرف القاعدة الجديدة، أو سكربتاً كتبه شخص ما بـ curl كما سوف نفعل نحن بعد قليل. فالتحقق في الكلاينت لراحة المستخدم، يعرف خطأه قبل أن ينتظر، والتحقق في السيرفر للحماية، وهو الوحيد الذي يعتمد عليه. ولذلك يجب أن يكون في العقد نفسه: الأنواع، والحقول الإلزامية، والحدود الدنيا والعليا للطول والقيمة، والقيم المسموحة، وأن يرفض السيرفر كل ما يخالفها برد واضح يقول أي حقل وما المشكلة، وأن يرفض الحقول التي لا يعرفها إذا كان قبولها خطراً، مثل حقل owner أو is_admin يرسله المستخدم في جسم الطلب.
تجربة عملية Lab: واجهة فعاليات صغيرة بلغة Python
سوف نبني واجهة لفعاليات تقنية يسجل فيها الحضور: قائمة الفعاليات، وتفاصيل فعالية، والتسجيل في فعالية، وإلغاء التسجيل، وإحصائية لكل فعالية. والبيانات في الذاكرة حتى يبقى التركيز على ال API نفسه، أما خدمة كاملة مع PostgreSQL والاختبارات وخط CI فقد بنيناها في خدمة Python الحقيقية. واخترنا FastAPI لأنه يولد ملف OpenAPI من الكود دون عمل إضافي، والمفاهيم نفسها في Express وSpring وASP.NET وLaravel. وكل الملفات في مجلد lab مع المقال.
التجهيز Setup
Container للواجهة، وContainer آخر للكلاينت فيه curl وPython، وكلاهما على شبكة Docker واحدة:
FROM python:3.13.18-slim
RUN pip install --no-cache-dir fastapi==0.163.2 uvicorn==0.54.0 "pydantic[email]==2.14.3"
WORKDIR /labFROM python:3.13.18-slim
RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
WORKDIR /labdocker network create sw2-net
docker build -t sw2-api:lab .
docker build -f Dockerfile.client -t sw2-apiclient:lab .
docker run -d --name sw2-api --network sw2-net -p 127.0.0.1:9549:8000 -v "$PWD:/lab" sw2-api:lab \
uvicorn app:app --host 0.0.0.0 --port 8000والملف app.py كاملاً، وفيه خطأ برمجي مقصود في دالة الإحصائية سوف نصل إليه:
"""A small events API: list events, read one, register for one, cancel a registration."""
import itertools, os
from datetime import datetime, timezone
from decimal import Decimal
from fastapi import FastAPI, Header, HTTPException, Query, Response
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import BaseModel, EmailStr, Field
app = FastAPI(title="Events API", version="1.0.0")
# ---------- data (in memory, enough for the lab) ----------
EVENTS = {
1: {"id": 1, "title": "لقاء DevOps الشهري", "starts_at": datetime(2026, 12, 3, 16, 0, tzinfo=timezone.utc),
"capacity": 3, "price": Decimal("0.00")},
2: {"id": 2, "title": "ورشة PostgreSQL", "starts_at": datetime(2026, 12, 10, 15, 30, tzinfo=timezone.utc),
"capacity": 20, "price": Decimal("150.00")},
3: {"id": 3, "title": "Data Night", "starts_at": datetime(2026, 12, 17, 17, 0, tzinfo=timezone.utc),
"capacity": 0, "price": Decimal("50.00")},
}
REGISTRATIONS: dict[int, dict] = {}
NEXT_ID = itertools.count(1) # ids are never reused, even after a delete
TOKENS = {"token-sara": "sara", "token-omar": "omar"} # who is calling
IDEMPOTENCY: dict[str, tuple[int, dict]] = {} # Idempotency-Key -> saved answer
# ---------- shapes of the messages ----------
class Event(BaseModel):
id: int
title: str
starts_at: datetime
capacity: int
price: Decimal = Field(description="SAR, sent as a string to keep the cents exact")
class EventPage(BaseModel):
items: list[Event]
next: str | None = Field(description="URL of the next page, null on the last page")
class NewRegistration(BaseModel):
name: str = Field(min_length=2, max_length=80)
email: EmailStr
class Registration(NewRegistration):
id: int
event_id: int
owner: str
# ---------- helpers ----------
def caller(authorization: str | None) -> str:
"""401 when we do not know who you are"""
token = (authorization or "").removeprefix("Bearer ")
if token not in TOKENS:
raise HTTPException(401, "missing or invalid token", headers={"WWW-Authenticate": "Bearer"})
return TOKENS[token]
def get_event(event_id: int) -> dict:
if event_id not in EVENTS:
raise HTTPException(404, f"event {event_id} not found")
return EVENTS[event_id]
async def bad_request(request, exc):
"""A body that is not JSON at all is a 400; JSON with wrong fields stays a 422."""
errors = exc.errors()
status = 400 if any(e["type"] == "json_invalid" for e in errors) else 422
return JSONResponse({"detail": [{k: e[k] for k in ("type", "loc", "msg")} for e in errors]}, status)
if not os.environ.get("DEFAULT_ERRORS"): # DEFAULT_ERRORS=1 shows what FastAPI does without it
app.add_exception_handler(RequestValidationError, bad_request)
# ---------- endpoints ----------
@app.get("/v1/events", response_model=EventPage)
def list_events(limit: int = Query(2, ge=1, le=50), offset: int = Query(0, ge=0)):
ids = sorted(EVENTS)[offset:offset + limit]
more = offset + limit < len(EVENTS)
return {"items": [EVENTS[i] for i in ids],
"next": f"/v1/events?limit={limit}&offset={offset + limit}" if more else None}
@app.get("/v1/events/{event_id}", response_model=Event)
def read_event(event_id: int):
return get_event(event_id)
@app.get("/v1/events/{event_id}/stats")
def event_stats(event_id: int):
event = get_event(event_id)
taken = sum(1 for r in REGISTRATIONS.values() if r["event_id"] == event_id)
return {"registered": taken, "full_percent": round(100 * taken / event["capacity"])} # bug: capacity 0
@app.post("/v1/events/{event_id}/registrations", status_code=201, response_model=Registration,
responses={401: {"description": "No token, or a token we do not know"},
404: {"description": "No event with this id"},
409: {"description": "Already registered, or the event is full"}})
def register(event_id: int, body: NewRegistration, response: Response,
authorization: str | None = Header(None), idempotency_key: str | None = Header(None)):
who = caller(authorization)
if idempotency_key in IDEMPOTENCY: # the same request again: same answer
status, saved = IDEMPOTENCY[idempotency_key]
response.status_code = status
response.headers["Location"] = f"/v1/registrations/{saved['id']}"
return saved
event = get_event(event_id)
taken = [r for r in REGISTRATIONS.values() if r["event_id"] == event_id]
if any(r["email"] == body.email for r in taken):
raise HTTPException(409, f"{body.email} is already registered for event {event_id}")
if len(taken) >= event["capacity"]:
raise HTTPException(409, f"event {event_id} is full")
reg = {"id": next(NEXT_ID), "event_id": event_id, "owner": who, **body.model_dump()}
REGISTRATIONS[reg["id"]] = reg
if idempotency_key:
IDEMPOTENCY[idempotency_key] = (201, reg)
response.headers["Location"] = f"/v1/registrations/{reg['id']}"
return reg
@app.delete("/v1/registrations/{reg_id}", status_code=204)
def cancel(reg_id: int, authorization: str | None = Header(None)):
who = caller(authorization)
reg = REGISTRATIONS.get(reg_id)
if reg is None:
raise HTTPException(404, f"registration {reg_id} not found")
if reg["owner"] != who:
raise HTTPException(403, "you can only cancel your own registration")
del REGISTRATIONS[reg_id]في الكود أعلاه لاحظ التالي:
- الكلاسات
EventوNewRegistrationوRegistrationهي العقد مكتوباً بالكود: أسماء الحقول وأنواعها وقيودها، مثل أن الاسم بين حرفين و80 حرفاً، وأن البريد يجب أن يكون بريداً صحيحاً. ومنها يتحقق FastAPI من الطلب، ويبني الرد، ويولد ملف OpenAPI. - السعر من النوع
Decimal، فيظهر في JSON كنص"150.00"وليس كرقم عشري. - التوكن في الترويسة
Authorization، والدالةcallerترفض بـ 401 مع الترويسةWWW-Authenticateالتي يطلبها المعيار مع هذا الرمز. - الإنشاء يعيد 201 مع الترويسة
Location، والإلغاء يعيد 204 دون جسم.
والسكربت calls.sh يرسل ثلاثة عشر طلباً بالترتيب، ويطبع كل رد كاملاً بالخيار curl -i، ونحذف منه سطر التاريخ فقط:
#!/bin/sh
# every call of the lab, in order. Run inside the client container: sh calls.sh
API=http://sw2-api:8000
step() { echo; echo "### $*"; }
call() { curl -s -i "$@" | grep -v '^date:'; echo; }
step "1) a list, first page"
call "$API/v1/events"
step "2) the next page, from the link in the answer"
call "$API/v1/events?limit=2&offset=2"
step "3) one event that does not exist"
call "$API/v1/events/99"
step "4) a path parameter that is not a number"
call "$API/v1/events/abc"
step "5) register without a token"
call -X POST "$API/v1/events/1/registrations" -H 'Content-Type: application/json' -d '{"name":"Sara","email":"[email protected]"}'
step "6) register with a token"
call -X POST "$API/v1/events/1/registrations" -H 'Authorization: Bearer token-sara' -H 'Content-Type: application/json' -d '{"name":"Sara","email":"[email protected]"}'
step "7) the same email again"
call -X POST "$API/v1/events/1/registrations" -H 'Authorization: Bearer token-sara' -H 'Content-Type: application/json' -d '{"name":"Sara","email":"[email protected]"}'
step "8) JSON with a bad email and a one-letter name"
call -X POST "$API/v1/events/1/registrations" -H 'Authorization: Bearer token-sara' -H 'Content-Type: application/json' -d '{"name":"S","email":"sara-at-example.com"}'
step "9) a body that is not JSON (a missing quote)"
call -X POST "$API/v1/events/1/registrations" -H 'Authorization: Bearer token-sara' -H 'Content-Type: application/json' -d '{"name":"Sara,"email":"[email protected]"}'
step "10) Omar tries to cancel Sara's registration"
call -X DELETE "$API/v1/registrations/1" -H 'Authorization: Bearer token-omar'
step "11) Sara cancels it, twice"
call -X DELETE "$API/v1/registrations/1" -H 'Authorization: Bearer token-sara'
call -X DELETE "$API/v1/registrations/1" -H 'Authorization: Bearer token-sara'
step "12) stats of an event with capacity 0"
call "$API/v1/events/3/stats"
step "13) a method the path does not support"
call -X PUT "$API/v1/events/1" -H 'Content-Type: application/json' -d '{}'docker run --rm --network sw2-net -v "$PWD:/lab" sw2-apiclient:lab sh calls.shالقراءة: قائمة، وصفحة تالية، وما لا يوجد
أول طلبين يقرآن القائمة:
### 1) a list, first page
HTTP/1.1 200 OK
server: uvicorn
content-length: 264
content-type: application/json
{"items":[{"id":1,"title":"لقاء DevOps الشهري","starts_at":"2026-12-03T16:00:00Z","capacity":3,"price":"0.00"},{"id":2,"title":"ورشة PostgreSQL","starts_at":"2026-12-10T15:30:00Z","capacity":20,"price":"150.00"}],"next":"/v1/events?limit=2&offset=2"}
### 2) the next page, from the link in the answer
HTTP/1.1 200 OK
server: uvicorn
content-length: 117
content-type: application/json
{"items":[{"id":3,"title":"Data Night","starts_at":"2026-12-17T17:00:00Z","capacity":0,"price":"50.00"}],"next":null}في المخرج أعلاه لاحظ التالي:
- سطر الحالة
200 OK، ثم الترويسات، ثم سطر فارغ، ثم الجسم. والترويسةcontent-type: application/jsonتقول للكلاينت كيف يقرأ الجسم، وcontent-lengthحجمه بالبايت، ولاحظ أن الرقم 264 أكبر من عدد الأحرف، لأن كل حرف عربي في UTF-8 يأخذ بايتين. - النص العربي ظهر كما هو دون
\u، والتاريخ بصيغة RFC 3339 مع Z، والسعر نص. - الرد ليس مصفوفة مباشرة، وإنما كائن فيه
itemsوnext، وهذا قرار مهم في العقد: إذا أعدت مصفوفة اليوم فلن تستطيع أن تضيف إليها رابط الصفحة التالية أو العدد الكلي غداً دون أن يتعطل الكلاينت. - الحقل
nextرابط الصفحة التالية جاهزاً، وفي الصفحة الأخيرة أصبحnull، فالكلاينت يتبع الرابط حتى يصبح فارغاً، ولا يحتاج أن يحسب الإزاحة بنفسه.
ثم فعالية غير موجودة، ثم معرف ليس رقماً:
### 3) one event that does not exist
HTTP/1.1 404 Not Found
server: uvicorn
content-length: 31
content-type: application/json
{"detail":"event 99 not found"}
### 4) a path parameter that is not a number
HTTP/1.1 422 Unprocessable Content
server: uvicorn
content-length: 139
content-type: application/json
{"detail":[{"type":"int_parsing","loc":["path","event_id"],"msg":"Input should be a valid integer, unable to parse string as an integer"}]}الرقم 99 رقم صحيح، فوصل الطلب إلى الدالة، ولم تجد الفعالية فأعادت 404 برسالة تقول ما الذي لم يوجد. أما abc فلم يصل إلى الدالة أصلاً، لأن FastAPI يعرف من العقد أن event_id رقم صحيح، فرفضه بـ 422 ورسالة فيها نوع الخطأ int_parsing ومكانه ["path", "event_id"]. وهذا الحقل loc مفيد جداً للكلاينت، لأنه يعرف منه أي حقل يعلم عليه باللون الأحمر في النموذج.
المصادقة Authentication والصلاحية: 401 ثم 403
التسجيل دون توكن، ثم عمر يحاول أن يلغي تسجيل سارة بتوكنه هو:
### 5) register without a token
HTTP/1.1 401 Unauthorized
server: uvicorn
www-authenticate: Bearer
content-length: 37
content-type: application/json
{"detail":"missing or invalid token"}
### 10) Omar tries to cancel Sara's registration
HTTP/1.1 403 Forbidden
server: uvicorn
content-length: 54
content-type: application/json
{"detail":"you can only cancel your own registration"}في الحالة الأولى لا نعرف من المرسل، فالرد 401 ومعه www-authenticate: Bearer الذي يقول للكلاينت أي نوع من المصادقة نتوقع. وفي الثانية نعرف أنه عمر، والتوكن صحيح، ولكن التسجيل ليس له، فالرد 403. والفرق يغير ما يفعله الكلاينت: مع 401 يعرض صفحة الدخول أو يجدد التوكن ويعيد الطلب، ومع 403 يعرض رسالة ولا فائدة من إعادة الطلب بنفس الحساب. والتحقق من أن المورد لصاحب الطلب، كما في السطر reg["owner"] != who، هو أهم سطر أمني في أي API، ونسيانه هو الخطر الأول في قائمة OWASP، وقد شرحناه بالتجربة في مقال أمن ال API.
الكتابة: 201 و409 و422 و400
سارة تسجل، ثم ترسل نفس التسجيل مرة أخرى، ثم ترسل اسماً من حرف واحد وبريداً دون @، ثم ترسل جسماً ينقصه علامة تنصيص:
### 6) register with a token
HTTP/1.1 201 Created
server: uvicorn
content-length: 77
content-type: application/json
location: /v1/registrations/1
{"name":"Sara","email":"[email protected]","id":1,"event_id":1,"owner":"sara"}
### 7) the same email again
HTTP/1.1 409 Conflict
server: uvicorn
content-length: 63
content-type: application/json
{"detail":"[email protected] is already registered for event 1"}
### 8) JSON with a bad email and a one-letter name
HTTP/1.1 422 Unprocessable Content
server: uvicorn
content-length: 239
content-type: application/json
{"detail":[{"type":"string_too_short","loc":["body","name"],"msg":"String should have at least 2 characters"},{"type":"value_error","loc":["body","email"],"msg":"value is not a valid email address: An email address must have an @-sign."}]}
### 9) a body that is not JSON (a missing quote)
HTTP/1.1 400 Bad Request
server: uvicorn
content-length: 80
content-type: application/json
{"detail":[{"type":"json_invalid","loc":["body",15],"msg":"JSON decode error"}]}في المخرج أعلاه لاحظ التالي:
- الإنشاء أعاد
201 Createdوليس 200، ومعهlocation: /v1/registrations/1، والجسم هو المورد كما حفظ، ومعه الحقول التي أضافها السيرفر، المعرف والمالك، فلا يحتاج الكلاينت طلباً آخر ليعرفها. - التسجيل المكرر أعاد 409: الطلب صحيح الصيغة والحقول، ولكنه يتعارض مع حالة موجودة، والرسالة تقول السبب.
- الحقول الخاطئة أعادت 422 مع خطأين معاً في نفس الرد، وليس أول خطأ فقط، وهذا يوفر على المستخدم أن يصلح حقلاً ثم يكتشف الثاني.
- الجسم غير الصالح أعاد 400 مع النوع
json_invalidومكان الخطأ في النص، الحرف رقم 15.
وهذا السطر الأخير لم يكن هكذا في البداية، فعندما أرسلنا أول مرة جسماً غير صالح كان رد FastAPI هو 422 وليس 400. والملف app.py يقرأ متغير البيئة DEFAULT_ERRORS الذي يعيد السلوك الافتراضي، وهذا رد نفس الطلب على نسخة تعمل به:
HTTP/1.1 422 Unprocessable Content
server: uvicorn
content-length: 133
content-type: application/json
{"detail":[{"type":"json_invalid","loc":["body",15],"msg":"JSON decode error","input":{},"ctx":{"error":"Expecting ',' delimiter"}}]}FastAPI يعامل JSON غير الصالح كخطأ تحقق Validation مثل أي حقل خاطئ، ويرد عليه بـ 422 كما يذكر توثيق معالجة الأخطاء. وهل هذا خطأ؟ ليس خطأ صريحاً في المعيار، ولكن المعنى الشائع عند أغلب الكلاينت أن 400 تعني «طلبك لا يقرأ أصلاً»، و422 تعني «قرأناه والقيم لا تقبل»، والكلاينت الذي يعرض أخطاء 422 بجانب الحقول لن يعرف أين يعرض «JSON decode error». ولاحظ أيضاً أن الرد الافتراضي فيه الحقلان input وctx، والأول قد يعيد للكلاينت قيماً أرسلها، وهذا قد يكون مشكلة إذا كانت حساسة. لذلك أضفنا الدالة bad_request التي تفرق بين الحالتين وتعيد الحقول الثلاثة فقط، وهذا مثال على قاعدة عامة: الإطار يعطيك قرارات افتراضية للعقد، وعليك أن تراجعها كما تراجع كودك.
الحذف DELETE مرتين: 204 ثم 404
### 11) Sara cancels it, twice
HTTP/1.1 204 No Content
server: uvicorn
content-type: application/json
HTTP/1.1 404 Not Found
server: uvicorn
content-length: 37
content-type: application/json
{"detail":"registration 1 not found"}الحذف الأول أعاد 204 دون جسم، والثاني 404 لأن التسجيل لم يعد موجوداً. وقد يتساءل البعض: أليس DELETE قابلاً للتكرار؟ فلماذا تغير الرد؟ والإجابة أن القابلية للتكرار في المعيار عن الأثر في السيرفر وليس عن الرد، فبعد الطلب الأول والثاني الحالة نفسها، التسجيل غير موجود، والكلاينت الذي أعاد الطلب بعد انقطاع يجب أن يفهم 404 هنا كـ «تم». ولاحظ تفصيلاً صغيراً في الرد الأول: الترويسة content-type: application/json موجودة مع أنه لا يوجد جسم، وهذا سلوك FastAPI الافتراضي عندما تكتب status_code=204 فقط، وهو غير ضار مع أغلب الكلاينت، وإذا أردت إزالته فاجعل الدالة تعيد Response(status_code=204) صراحة.
خطأ في كود السيرفر: 500
الفعالية الثالثة سعتها صفر، ودالة الإحصائية تقسم على السعة:
### 12) stats of an event with capacity 0
HTTP/1.1 500 Internal Server Error
server: uvicorn
content-length: 21
content-type: text/plain; charset=utf-8
Internal Server Errorالكلاينت حصل على 500 ونص عادي Internal Server Error، وليس JSON، ولا يعرف أي شيء آخر. وهذا جيد من ناحية الأمان، فلا يجب أن يرى المستخدم تفاصيل الكود، ولكن أين التفاصيل؟ في سجل السيرفر، وهذا جزء منه، واختصرنا السطور الوسطى التي تمر بها الطبقات الداخلية للإطار:
INFO: 172.24.0.7:60534 - "GET /v1/events/3/stats HTTP/1.1" 500 Internal Server Error
ERROR: Exception in ASGI application
Traceback (most recent call last):
...
File "/lab/app.py", line 97, in event_stats
return {"registered": taken, "full_percent": round(100 * taken / event["capacity"])} # bug: capacity 0
~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~
ZeroDivisionError: division by zeroالسجل يقول الملف والسطر والعبارة بالضبط، وقد شرحنا كيف تقرأ ال Stack Trace من آخره في مقال تصحيح الأخطاء. والدرس هنا للعقد: الكلاينت الذي يستقبل 500 لا يستطيع أن يصلح شيئاً، فلا تجعل أخطاء المنطق المتوقعة تصل إلى 500، فالفعالية ذات السعة صفر حالة يجب أن يتعامل معها الكود، والخطأ 500 يجب أن يبقى للأخطاء التي لم تتوقعها فعلاً. وفي الإنتاج أضف إلى كل رد معرف طلب Request ID، يظهر للمستخدم وفي السجل معاً، حتى يرسله لك فتجد السطر المطلوب.
وآخر طلب يرسل PUT إلى عنوان يقبل GET فقط:
### 13) a method the path does not support
HTTP/1.1 405 Method Not Allowed
server: uvicorn
allow: GET
content-length: 31
content-type: application/json
{"detail":"Method Not Allowed"}الرد 405 مع الترويسة allow: GET التي تقول للكلاينت ما المسموح، وهذا ما يطلبه المعيار مع هذا الرمز.
مشكلة واجهناها: رقم تسجيل أعيد استخدامه
في النسخة الأولى من app.py كان رقم التسجيل الجديد يحسب بالسطر len(REGISTRATIONS) + 1، وبعد أن شغلنا calls.sh الذي يحذف التسجيل رقم 1، شغلنا السكربت retry.sh الذي سوف نشرحه في الفقرة التالية، فكان أول سطر في مخرجه:
## without a key: the same request twice
201 /v1/registrations/1
409
## with a key: the retry gets the first answer back
201 /v1/registrations/2
201 /v1/registrations/2
{"registered":2,"full_percent":10}التسجيل الجديد أخذ الرقم 1 مرة أخرى، لأن عدد التسجيلات بعد الحذف أصبح صفراً. وهذا يعني أن أي كلاينت حفظ الرابط /v1/registrations/1 لتسجيل سارة الملغى أصبح الآن يشير إلى تسجيل عمر، فإذا أرسل حذفاً متأخراً، أو عرض بياناته، فقد تعامل مع مورد شخص آخر. والقاعدة في العقد أن معرف المورد لا يعاد استخدامه أبداً، والحل في الكود عداد لا يرجع إلى الخلف، كما في السطر NEXT_ID = itertools.count(1)، وفي قاعدة البيانات هذا ما يفعله التسلسل Sequence أو المعرفات العشوائية مثل UUID.
إعادة المحاولة الآمنة Idempotency: ماذا لو لم يصل الرد؟
تخيل أن تطبيق الجوال أرسل طلب التسجيل، ونفذه السيرفر، ثم انقطعت الشبكة قبل أن يصل الرد. التطبيق لا يعرف هل نجح الطلب أم لا، فإذا أعاده وكانت العملية دفعاً فقد يدفع المستخدم مرتين. وPOST ليست قابلة للتكرار بطبيعتها، والحل الشائع أن يرسل الكلاينت مع الطلب مفتاحاً فريداً في الترويسة Idempotency-Key، فيحفظ السيرفر الرد الأول مع المفتاح، وإذا وصل نفس المفتاح مرة أخرى أعاد الرد المحفوظ دون أن ينفذ شيئاً. وهذه الترويسة ما زالت مسودة معيار في IETF، ولكنها مستخدمة منذ سنوات في واجهات الدفع مثل Stripe. والسكربت retry.sh يرسل نفس الطلب مرتين دون مفتاح، ثم مرتين بنفس المفتاح:
#!/bin/sh
# the client did not get the answer and sends the same POST again, with and without Idempotency-Key
API=http://sw2-api:8000
post() { curl -s -o /dev/null -w "%{http_code} %header{location}\n" -X POST "$API/v1/events/2/registrations" \
-H 'Authorization: Bearer token-omar' -H 'Content-Type: application/json' "$@"; }
echo "## without a key: the same request twice"
post -d '{"name":"Omar","email":"[email protected]"}'
post -d '{"name":"Omar","email":"[email protected]"}'
echo "## with a key: the retry gets the first answer back"
post -H 'Idempotency-Key: 7c0a1f9e' -d '{"name":"Omar","email":"[email protected]"}'
post -H 'Idempotency-Key: 7c0a1f9e' -d '{"name":"Omar","email":"[email protected]"}'
curl -s "$API/v1/events/2/stats"; echo## without a key: the same request twice
201 /v1/registrations/2
409
## with a key: the retry gets the first answer back
201 /v1/registrations/3
201 /v1/registrations/3
{"registered":2,"full_percent":10}دون مفتاح، الطلب الثاني أعاد 409 لأن البريد مسجل، أي أن الكلاينت الذي أعاد الطلب بعد انقطاع سوف يعرض للمستخدم «أنت مسجل مسبقاً» مع أن تسجيله نجح للتو، وفي واجهة لا يوجد فيها فحص للتكرار كان سوف يحصل على تسجيلين. ومع المفتاح أعاد الطلب الثاني نفس الرد 201 بنفس الرقم 3، والإحصائية تقول تسجيلين فقط. وهذا تطبيق بسيط في الذاكرة، أما في الإنتاج فتحفظ المفاتيح في قاعدة البيانات داخل نفس المعاملة، وتعالج حالة وصول الطلبين في نفس اللحظة، وقد شرحنا ذلك بالتفصيل في مقال Idempotency. والصورة التالية تبين الحالتين:

من جهة الكلاينت: JavaScript وPython يقرآن نفس الرد
حتى الآن رأينا ال API من curl، والآن نقرؤه من كود حقيقي في لغتين، لأن الفروق بين مكتبات الكلاينت تسبب أخطاء لا تظهر في curl. السكربت client.mjs يعمل على Node.js 22:
// The same API from JavaScript: fetch() does not throw on 404, and big numbers in JSON lose digits.
const API = "http://sw2-api:8000";
for (const path of ["/v1/events/1", "/v1/events/99"]) {
const res = await fetch(API + path);
console.log(path, "->", res.status, res.ok ? "ok" : "NOT ok", await res.json());
}
const text = '{"id": 9007199254740993, "id_str": "9007199254740993", "price": 0.1}';
const obj = JSON.parse(text);
console.log("id :", obj.id);
console.log("id_str :", obj.id_str);
console.log("price*3:", obj.price * 3);docker run --rm --network sw2-net -v "$PWD:/lab" -w /lab node:22-alpine node client.mjs/v1/events/1 -> 200 ok {
id: 1,
title: 'لقاء DevOps الشهري',
starts_at: '2026-12-03T16:00:00Z',
capacity: 3,
price: '0.00'
}
/v1/events/99 -> 404 NOT ok { detail: 'event 99 not found' }
id : 9007199254740992
id_str : 9007199254740993
price*3: 0.30000000000000004والسكربت client.py يفعل الشيء نفسه بمكتبة Python القياسية:
"""The same API from Python's standard library: urllib raises an exception on 4xx and 5xx."""
import json, urllib.error, urllib.request
from decimal import Decimal
API = "http://sw2-api:8000"
for path in ("/v1/events/2", "/v1/events/99"):
try:
with urllib.request.urlopen(API + path, timeout=5) as res:
event = json.load(res, parse_float=Decimal)
print(path, "->", res.status, event["title"], Decimal(event["price"]) * 3)
except urllib.error.HTTPError as e:
print(path, "->", e.code, json.load(e))
print(json.loads('{"id": 9007199254740993}')["id"])/v1/events/2 -> 200 ورشة PostgreSQL 450.00
/v1/events/99 -> 404 {'detail': 'event 99 not found'}
9007199254740993في المخرجين أعلاه لاحظ التالي:
- الدالة
fetchلا ترمي استثناء عند 404، وإنما تعيد الرد والحقلres.okقيمته false، كما يذكر توثيق MDN، فإذا كتبتconst data = await res.json()دون أن تفحصokفسوف يعمل كودك على رسالة الخطأ كأنها فعالية. أماurllibفي Python فترمي HTTPError عند 4xx و5xx. ولا توجد طريقة صحيحة وأخرى خاطئة، ولكن يجب أن تعرف سلوك مكتبتك قبل أن تكتب أول سطر. - العدد
9007199254740993أصبح في JavaScript9007199254740992، أي أن خانة ضاعت بصمت دون أي خطأ، بينما قرأه Python صحيحاً لأن الأعداد الصحيحة فيه بلا حد. فلو كان هذا معرف طلب أو رقم حساب لعرض تطبيق الويب طلباً آخر. والنسخة النصيةid_strوصلت سليمة، ولذلك ترسل الواجهات الكبيرة المعرفات الطويلة كنص. 0.1 * 3أعطت0.30000000000000004في JavaScript، أما في Python فقرأنا السعر كنص ثم حولناه إلىDecimalفكان المجموع450.00بالضبط. وهذا سبب إرسال المبالغ كنص.
أساسيات التقسيم إلى صفحات Pagination والإصدارات Versioning
في التجربة استخدمنا التقسيم بالإزاحة Offset Pagination: limit لعدد العناصر، وoffset لعدد ما يتجاوزه، ووضعنا حداً أعلى 50 في العقد نفسه بـ le=50، لأن الواجهة التي تقبل limit=1000000 تسمح لأي كلاينت بأن يطلب الجدول كله في طلب واحد. وهذه الطريقة سهلة، ولها مشكلتان معروفتان: تبطؤ مع الإزاحات الكبيرة لأن قاعدة البيانات تقرأ الصفوف المتجاوزة ثم ترميها، وتكرر أو تفوت عناصر إذا أضيف عنصر جديد بين طلب صفحة والتي بعدها. والبديل هو التقسيم بالمؤشر Cursor Pagination، أي أن تقول «أعطني ما بعد آخر عنصر رأيته»، وقد شرحناه مع أمثلته في مقال تصميم الواجهات. والقاعدة التي تجعل الانتقال بينهما ممكناً لاحقاً دون تعطيل الكلاينت هي ما فعلناه: أن يتبع الكلاينت الرابط next كما هو، ولا يبنيه بنفسه.
أما الإصدار v1 في الرابط فهو وعد بأن العقد لن يتغير بطريقة تعطل الكلاينت. والتغييرات تنقسم إلى نوعين: متوافقة مع الإصدار السابق Backward Compatible، مثل إضافة حقل جديد في الرد أو إضافة Endpoint جديد، وهذه تنشر في نفس الإصدار، لأن الكلاينت المكتوب جيداً يتجاهل الحقول التي لا يعرفها. وغير متوافقة Breaking، مثل حذف حقل أو تغيير اسمه أو نوعه، أو تحويل حقل اختياري إلى إلزامي، أو تغيير رمز حالة، وهذه تحتاج إصداراً جديداً v2 يعمل بجانب القديم فترة معلنة. وتفاصيل الطرق الأخرى للإصدارات، والإيقاف التدريجي Deprecation، في نفس المقال.
ملف OpenAPI: العقد مكتوباً، وما الذي ينقصه؟
OpenAPI صيغة قياسية لوصف Web API في ملف JSON أو YAML، فيها كل Endpoint وطرقه ومعاملاته وأشكال طلباته وردوده، وآخر إصدار مستخدم على نطاق واسع هو OpenAPI 3.1. ومن هذا الملف تولد صفحات التوثيق، ومكتبات الكلاينت بلغات مختلفة، واختبارات تتحقق من أن الرد يطابق العقد. وFastAPI يولده من الكود في العنوان /openapi.json، ويعرضه كصفحة تفاعلية في /docs بأداة Swagger UI. والصورة التالية من الواجهة نفسها التي نعمل عليها:

ولكن هل الملف يصف ال API كاملاً؟ السكربت openapi_paths.py يطبع كل عملية مع رموز الحالة التي يذكرها الملف، وشغلناه على الملف كما ولده FastAPI أول مرة:
"""Print each operation in an OpenAPI file with the status codes it documents.
usage: python openapi_paths.py openapi.json"""
import json, sys
doc = json.load(open(sys.argv[1], encoding="utf-8"))
print("openapi", doc["openapi"], "|", doc["info"]["title"], doc["info"]["version"])
for path, ops in doc["paths"].items():
for method, op in ops.items():
print(f"{method.upper():7} {path:40} {' '.join(sorted(op['responses']))}")openapi 3.1.0 | Events API 1.0.0
GET /v1/events 200 422
GET /v1/events/{event_id} 200 422
GET /v1/events/{event_id}/stats 200 422
POST /v1/events/{event_id}/registrations 201 422
DELETE /v1/registrations/{reg_id} 204 422
openapi 3.1.0 | Events API 1.0.0
GET /v1/events 200 422
GET /v1/events/{event_id} 200 422
GET /v1/events/{event_id}/stats 200 422
POST /v1/events/{event_id}/registrations 201 401 404 409 422
DELETE /v1/registrations/{reg_id} 204 422القسم الأول هو الملف الأصلي: كل عملية تذكر رمز النجاح و422 فقط، أي أن العقد المكتوب لا يعرف شيئاً عن 401 و403 و404 و409 التي رأيناها كلها في التجربة. والسبب أن FastAPI يعرف ما في توقيع الدالة، ولكنه لا يعرف ما ترميه من داخلها بـ HTTPException. فالكلاينت الذي يولد كوده من هذا الملف لن يعرف أن عليه أن يتعامل مع 409. والحل أن تضيف الردود يدوياً بالمعامل responses كما في توثيق الردود الإضافية، وهذا ما فعلناه لعملية التسجيل، فأصبحت في القسم الثاني تذكر 401 و404 و409. والصورة التالية للعملية نفسها في Swagger UI بعد الإضافة:

ولاحظ في أسفل الصورة شيئاً آخر: شكل خطأ 422 في الملف ما زال يذكر الحقلين input وctx، مع أن الدالة bad_request التي أضفناها تحذفهما من الرد الحقيقي. أي أن العقد المكتوب والسلوك الفعلي اختلفا بسبب تعديل صغير لم يحدث الملف، وهذا ما يسمى انحراف العقد Contract Drift. ولا تكتشفه بالقراءة، وإنما باختبار يرسل الطلبات ويقارن كل رد بالملف، وقد بنينا هذا النوع من الاختبارات في خط CI في مقال اختبار ال API. والصورة التالية تبين أين يقع الملف بين الكود والأدوات:

وهناك طريقتان لكتابة هذا الملف. في طريقة الكود أولاً Code-first، كما فعلنا، تكتب الكود ويولد الإطار الملف، وهي أسرع لفريق واحد يملك الطرفين. وفي طريقة التصميم أولاً Design-first يكتب الفريق ملف OpenAPI ويراجعه مع فريق الجوال أو الشريك الخارجي قبل أن يكتب أحد سطراً من الكود، ثم يبني كل طرف جهته على العقد المتفق عليه، ويستطيع فريق الجوال أن يعمل على سيرفر وهمي Mock Server يولد من الملف حتى يجهز السيرفر الحقيقي. والطريقة الثانية أبطأ في البداية، ولكنها تكشف الخلاف على الأسماء والأخطاء والحقول الإلزامية في اجتماع واحد بدلاً من أن يكتشف بعد أسابيع من الكود.
أخطاء شائعة Common Mistakes
- 200 لكل شيء والخطأ في الجسم: مثل
{"success": false}مع 200، فلا تعرف المكتبات وال Proxies والمراقبة أن هناك خطأ، ولا يعيد أحد المحاولة بشكل صحيح. - الخلط بين 401 و403: الأول للهوية المجهولة، والثاني للصلاحية الناقصة، والكلاينت يتصرف بشكل مختلف تماماً مع كل منهما.
- 500 لأخطاء متوقعة: القسمة على صفر، والمورد المحذوف، والقيمة الفارغة، كلها حالات في المنطق يجب أن يكون لها رد واضح.
- تفاصيل الكود في الرد: ال Stack Trace واستعلام SQL مكانهما السجل، وليس جسم الرد.
- إعادة استخدام المعرفات: كما في المشكلة التي واجهناها، الرابط القديم يشير إلى مورد شخص آخر.
- المعرفات الكبيرة والمبالغ كأرقام JSON: تفقد خاناتها في JavaScript وكسورها في الأعداد العشرية.
- تواريخ دون منطقة زمنية أو بصيغة محلية: استخدم RFC 3339 مع UTC، واترك التحويل إلى التوقيت المحلي للواجهة.
- مصفوفة في جذر رد القائمة: لا يمكن أن تضيف إليها رابط الصفحة التالية لاحقاً دون تعطيل الكلاينت.
- قائمة بلا حد أعلى:
limitدون سقف يسمح بطلب الجدول كله. - إعادة POST تلقائياً دون مفتاح: قد ينشئ طلباً ثانياً أو يدفع مرتين.
- الوثوق بملف OpenAPI المولد كما هو: لا يعرف الأخطاء التي ترميها من داخل الدوال، ويختلف عن السلوك عندما تعدل الأخطاء بنفسك.
- عدم فحص الرمز في الكلاينت:
fetchلا ترمي عند 404، فافحصres.okقبل قراءة الجسم.
قائمة تحقق Checklist قبل أن تنشر أول API
- كل Endpoint له طريقة تناسب أثره: GET للقراءة فقط، وPOST للإنشاء، وDELETE للحذف.
- كل رد خطأ له رمز من الجدول، ورسالة تقول السبب، وشكل واحد في كل ال API.
- الإنشاء يعيد 201 مع
Location، والحذف يعيد 204. - 401 مع
WWW-Authenticateللهوية، و403 للصلاحية، والتحقق من مالك المورد في كل عملية. - JSON بترميز UTF-8، والتواريخ RFC 3339 مع UTC، والمبالغ والمعرفات الطويلة نصوص.
- القوائم كائن فيه
itemsورابطnext، مع حد أعلى للحجم. - العمليات التي قد تعاد، مثل الدفع والتسجيل، تقبل
Idempotency-Key. - الإصدار في الرابط، والتغييرات غير المتوافقة في إصدار جديد فقط.
- ملف OpenAPI فيه كل رموز الأخطاء، واختبار في CI يقارن الردود الحقيقية به.
- كل خطأ 500 يسجل مع معرف طلب يظهر للمستخدم.
حذف المختبر Cleanup
docker rm -f sw2-api
docker network rm sw2-net
docker rmi sw2-api:lab sw2-apiclient:labماذا تقرأ بعد ذلك؟ Next Steps
هذا المقال في مرحلة تصميم الأنظمة بعد المدخل إلى تصميم الأنظمة، وبعده تأتي المقالات التي تأخذ كل جزء منه إلى العمق: تصميم ال API الذي يبقى متوافقاً مع عملائه، وأمنه، واختباره، والعملية الآمنة عند التكرار، وتحديد معدل الطلبات.
دليلHTTP وHTTPS ببساطة: ماذا يحدث بين الرابط والصفحةماذا يحدث بين كتابة الرابط وظهور الصفحة، وكيف تقرأ الطلب والرد ورموز مثل 502 و504، ولماذا يكلف الاتصال الجديد أكثر.
دليلكيف تصمم API يبقى متوافقاً مع عملائه بعد سنةمبادئ تصميم API يتطور دون أن يعطل التطبيقات التي تعتمد عليه، وكيف تختار الشكل المناسب لنظامك.
دليلأمن ال API بالأمثلة مع OWASP API Security Top 10أشهر عشرة مخاطر في واجهات API كما ترتبها OWASP، ولكل خطر مثال لكود ضعيف وكيف تصلحه وتختبره.
دليلاختبار ال API مع Bruno وPostman في خط CIكيف تكتب اختبارات API تعيش في المستودع وتتحقق من العقد والصلاحيات، وتعمل في خط CI مع Bruno أو Postman.
دليلIdempotency: كيف تجعل العملية آمنة عند تكرارهالماذا تصل الرسالة نفسها أكثر من مرة، وكيف تكتب مستهلكاً يطبقها مرة واحدة فقط مهما تكررت.
دليلتحديد معدل الطلبات Rate Limiting وخوارزمياتهكيف تعمل خوارزميات تحديد معدل الطلبات، وأيها يناسب واجهتك، وكيف تطبقها على عدة سيرفرات وترد بالرمز 429 الصحيح.الخلاصة Summary
وصلنا لنهاية الموضوع، وأهم ما فيه:
- ال API عقد بين برنامجين: العنوان والطريقة والمدخلات والمخرجات والأخطاء والمصادقة، والكود خلفه تفصيل يمكن أن يتغير ما دام العقد ثابتاً.
- الطلب طريقة وعنوان وترويسات وجسم، والرد رمز حالة وترويسات وجسم، والطرق GET وPUT وDELETE قابلة للتكرار وPOST ليست كذلك.
- JSON فيه ستة أنواع فقط، فالتواريخ نصوص بصيغة RFC 3339، والمبالغ والمعرفات الكبيرة نصوص، وإلا ضاعت خانة كما رأيت في JavaScript.
- الرقم الأول من رمز الحالة يقول من المخطئ، و4xx لا يصلحها التكرار، و5xx قد يصلحها إذا كانت العملية آمنة للتكرار.
- في التجربة صنعنا 200 و201 و204 و400 و401 و403 و404 و405 و409 و422 و500 على واجهة حقيقية، ورأينا ثلاث مشاكل: FastAPI يرد على JSON غير الصالح بـ 422، ومعرف أعيد استخدامه بعد الحذف، وملف OpenAPI لا يذكر الأخطاء التي ترمى من داخل الدوال.
- مفتاح
Idempotency-Keyجعل إعادة POST تعيد نفس الرد بدلاً من 409 أو تسجيل ثان.
سجل التحديثات Changelog
- 18 نوفمبر 2026: كتابة المقال، وتنفيذ التجربة على Docker Engine 29.8.0 مع Python 3.13.18 وFastAPI 0.163.2 وStarlette 1.10.0 وPydantic 2.14.3 وuvicorn 0.54.0 وcurl 8.14.1 وNode.js 22.23.4.