تصميم الـ API

عقد الـ HTTP هو الشيء الوحيد الذي تلمسه أربعة stacks: الـ backend ينتجه، و Angular و Android و iOS يستهلكونه — واثنان منهم لا يُعاد نشرهما مع الخادم. كل استجابة غير 2xx تخرج بشكل RFC 9457 واحد؛ جسم الـ 500 يحمل traceId وعنواناً ثابتاً، ولا يحمل نص exception أبداً — التفاصيل تذهب إلى الـ log. الإصدار عبر الـ URL (/v1/...)، وداخل الإصدار الواحد الإضافة فقط: حذف حقل أو إعادة تسميته أو تضييق نوعه يعني إصدارًا جديدًا. الإصدار القديم يبقى حيًّا ما دام هناك تطبيق native مثبّت يستخدمه — والحدّ الأدنى الذي يفرضه الـ API هو ما يجعل إيقافه آمناً، لا المتجر. كل مجموعة تُرجِع items وpage وpageSize وtotal. أي طلب غير GET قد يُعاد إرساله يأخذ Idempotency-Key، والخادم يعيد النتيجة المخزّنة ولا يرفض المحاولة. وثيقة OpenAPI تُولَّد من الكود وتُلتزَم في الـ repo، والـ CI يقارنها ويكسر الـ PR عند أي تغيير كاسر. التصريح بالصلاحية يكون في الخادم لكل endpoint — الـ guard في الواجهة تجربة استخدام لا حماية.

flowchart LR
  Api[".NET API<br/>produces the contract"] --> Spec["OpenAPI document<br/>committed, diffed in CI"]
  Spec --> Web["Angular"]
  Spec --> And["Android"]
  Spec --> Ios["iOS"]

للتفاصيل الكاملة والأمثلة انظر النسخة الإنجليزية: API Design.