كيفية بناء REST API: التصميم والأمان والنشر

لبناء REST API، اكتب قائمة بـالموارد التي يديرها تطبيقك (المستخدمون والطلبات والحجوزات)، وأعطِ كل مورد رابطاً مثل /orders و/orders/{id}، واستخدم طرق HTTP للعمليات: GET للقراءة، وPOST للإنشاء، وPATCH للتحديث، وDELETE للحذف. أعِد البيانات بصيغة JSON مع رموز حالة واضحة، وتحقق من كل مدخل، واشترط المصادقة والتحقق من صلاحية الوصول لكل سجل على الخادم، وقسّم القوائم إلى صفحات. بعد ذلك وثّق نقاط الوصول وانشر الـ API خلف HTTPS.

يغطي هذا الدليل قرارات التصميم، ومجموعة مسارات مُطبّقة كمثال، وتعليمات جاهزة لأداة بناء التطبيقات بالذكاء الاصطناعي، والأخطاء التي تسبب ثغرات أمنية. إذا كانت واجهات API جديدة عليك، فابدأ بـما هي واجهة API.

متى تحتاج إلى REST API

• تحتاج واجهتك الأمامية على الويب إلى حفظ البيانات وتحميلها من خادم
• يحتاج تطبيق موبايل أو شريك أو أداة أتمتة إلى الوصول إلى بياناتك
• تُرسل إليك خدمات أخرى أحداثاً (Webhooks)
• تقسّم العمل بين فريق الواجهة الأمامية وفريق الخادم

REST هو الأسلوب الأكثر شيوعاً، لكنه ليس الوحيد. يشرح REST مقابل GraphQL متى تكون نقطة استعلام مرنة واحدة أنسب.

صمّم أولاً: الموارد والمسارات

اكتب الأسماء الموجودة في تطبيقك وما يفعله الناس بها. مثال على تطبيق حجوزات بسيط:

هذه المسارات تقابل عمليات الإنشاء والقراءة والتحديث والحذف؛ انظر ما هو CRUD. وهذه قواعد تستحق الالتزام بها:

• أسماء جمع بدون أفعال في الروابط: /bookings وليس /getBookings.
• تداخل مستوى واحد فقط عندما يوضح الملكية: /bookings/{id}/notes.
• العمليات التي ليست من نوع CRUD يمكن أن تكون موارد فرعية: POST /bookings/{id}/cancel أوضح من PATCH يحمل معنى خفياً.
• تسمية موحدة للحقول، مثل created_at في كل مكان.

رموز الحالة والأخطاء

استخدم رموز HTTP القياسية حتى يعرف العميل ما حدث دون تحليل النص:

أعِد الأخطاء بشكل JSON موحد واحد، مثلاً {"error": {"code": "slot_taken", "message": "هذا الوقت لم يعد متاحاً."}}، ولا تُضمّن أبداً في الاستجابات تتبّع الأخطاء (stack traces) أو أخطاء قاعدة البيانات.

الخيارات والمفاضلات

خطوة بخطوة

1. اكتب الموارد والمسارات كما سبق، مع تحديد من يحق له استدعاء كل مسار.
2. صمّم البيانات في قاعدة بياناتك بالحقول والعلاقات التي تحتاجها.
3. ابنِ مسارات القراءة أولاً، ثم الإنشاء والتحديث والحذف.
4. تحقق من المدخلات في كل عملية كتابة باستخدام مكتبة مخططات (schema): الحقول المطلوبة والأنواع والأطوال والقيم المسموحة. وارفض الحقول غير المعروفة.
5. أضف المصادقة، ثم التفويض لكل سجل: فتح /bookings/42 يجب أن يتحقق من أن الحجز 42 يخص المستخدم الحالي، لا أن يكتفي بالتحقق من أن أحداً قد سجّل الدخول.
6. قسّم كل قائمة إلى صفحات وحدّد الحد الأقصى لحجم الصفحة.
7. حدّد عدد الطلبات لتسجيل الدخول والمسارات المكلفة. انظر حدود الطلبات.
8. اضبط CORS فقط إذا كان يجب أن تستدعي المتصفحات على نطاقات أخرى الـ API، واذكر تلك المصادر بشكل صريح. يشرح كيفية إصلاح أخطاء CORS الأخطاء التي ستراها.
9. اكتب التوثيق والاختبارات لكل مسار، بما في ذلك حالات الفشل.
10. انشر مع وضع الأسرار في متغيرات البيئة، وHTTPS، والسجلات، وفحص للصحة.

تعليمات لأداة البناء بالذكاء الاصطناعي

الهيكل الأساسي:

أنشئ REST API للحجوزات بهذه المسارات: GET /api/health، وGET /api/bookings (مع ترقيم الصفحات، بحد أقصى 50 في الصفحة)، وPOST /api/bookings، وGET /api/bookings/:id، وPATCH /api/bookings/:id، وDELETE /api/bookings/:id. خزّن البيانات في قاعدة بياناتنا. تحقق من أجسام الطلبات بمكتبة مخططات، وارفض الحقول غير المعروفة. أعِد أخطاء JSON بالشكل {"error": {"code", "message"}} مع رموز الحالة الصحيحة (400، 401، 403، 404، 409). احفظ الأسرار في متغيرات البيئة.

الأمان:

اشترط تسجيل الدخول على كل مسارات الحجوزات. في كل عملية قراءة وتحديث وحذف، تحقق على الخادم من أن الحجز يخص المستخدم الحالي، وأعِد 404 إذا لم يكن كذلك. لا تقبل أبداً معرّفات المستخدمين أو الأدوار من جسم الطلب. حدّد POST /api/bookings بعدد 20 طلباً في الدقيقة لكل مستخدم. سجّل الأخطاء على الخادم دون إعادة تتبّع الأخطاء للعميل.

التوثيق:

اكتب وصفاً بصيغة OpenAPI لهذه المسارات، وملف README قصيراً فيه أمثلة على الطلبات والاستجابات لكل مسار.

اختبار الـ API

اختبره من خارج الواجهة الأمامية، لأن المهاجمين سيفعلون ذلك:

• يعمل كل مسار مع مدخلات صحيحة ويُعيد الشكل ورمز الحالة الموثّقين
• المدخلات الناقصة أو غير الصالحة تُعيد 400 مع رسالة واضحة
• عدم وجود رمز يُعيد 401 في كل مسار محمي
• إذا طلب المستخدم A سجل المستخدم B عبر المعرّف، يحصل على 404 أو 403
• القوائم مقسمة إلى صفحات، والقيمة limit الكبيرة جداً مقيّدة بحد أقصى
• التكرارات أو التعارضات عند الإنشاء تُعيد 409 وليس 500
• حدود الطلبات تُعيد 429
• لا تحتوي استجابات الأخطاء على تتبّع أخطاء أو SQL أو أسرار
• يسمح CORS فقط بالمصادر التي تقصدها

أخطاء شائعة

• التحقق من تسجيل الدخول دون التحقق من الملكية. أكثر ثغرة شيوعاً في الـ API: أي مستخدم مسجل يستطيع قراءة أي سجل بتغيير المعرّف.
• الثقة بالعميل. الأسعار والأدوار ومعرّفات المستخدمين في جسم الطلب يمكن تعديلها.
• إعادة صفوف قاعدة البيانات كاملة. تتسرب تجزئات كلمات المرور والحقول الداخلية. اختر ما تتضمنه كل استجابة.
• قوائم بلا حد. طلب واحد لكل السجلات يمكن أن يبطئ التطبيق كله.
• 200 OK مع رسالة خطأ داخلها. لا يستطيع العملاء ولا أدوات المراقبة معرفة أن الطلب فشل.
• ضبط CORS على السماح بكل شيء في API يستخدم ملفات تعريف الارتباط.
• عدم وجود فحص صحة أو سجلات، فتعرف بالأعطال من شكاوى المستخدمين.

لمراجعة أشمل قبل الإطلاق، انظر قائمة التحقق الأمنية للتطبيقات المبنية بالذكاء الاصطناعي.

بناء REST API في Mythex

يمكنك أن تطلب من Mythex واجهة API كجزء من تطبيقك أو كخدمة مستقلة. تتضمن وصفة الوثائق REST API backend نصاً أولياً للطلب: حدد الإطار والمسارات، واطلب أخطاء JSON واضحة، واحفظ الأسرار في متغيرات البيئة، وأضف Dockerfile. تُنشر خوادم الحاويات بلغات Node وPython وC# وJava وغيرها عبر Dockerfile، ويتولى Mythex عملية النشر من Publish (واجهات API الخلفية). يمكن لمشروع أن يشغّل موقعاً وخادم API جنباً إلى جنب، ويمكنك التبديل بينهما في المعاينة. احفظ المفاتيح كأسرار للمشروع، وإذا كانت الـ API تحتاج إلى قاعدة بيانات فاطلبها في المحادثة. للمهام المجدولة الخلفية المرتبطة بالـ API، انظر كيفية تشغيل المهام الخلفية.

الأسئلة