كيفية بناء REST API: التصميم والأمان والنشر
لبناء REST API، اكتب قائمة بـالموارد التي يديرها تطبيقك (المستخدمون والطلبات والحجوزات)، وأعطِ كل مورد رابطاً مثل /orders و/orders/{id}، واستخدم طرق HTTP للعمليات: GET للقراءة، وPOST للإنشاء، وPATCH للتحديث، وDELETE للحذف. أعِد البيانات بصيغة JSON مع رموز حالة واضحة، وتحقق من كل مدخل، واشترط المصادقة والتحقق من صلاحية الوصول لكل سجل على الخادم، وقسّم القوائم إلى صفحات. بعد ذلك وثّق نقاط الوصول وانشر الـ API خلف HTTPS.
يغطي هذا الدليل قرارات التصميم، ومجموعة مسارات عملية، وطلبات لمنشئ تطبيقات بالذكاء الاصطناعي مثل Mythex، والأخطاء التي تسبب ثغرات أمنية. إذا كانت واجهات API جديدة عليك، فابدأ بـما هي واجهة API.
متى تحتاج إلى REST API
- تحتاج واجهتك الأمامية على الويب إلى حفظ البيانات وتحميلها من خادم
- يحتاج تطبيق موبايل أو شريك أو أداة أتمتة إلى الوصول إلى بياناتك
- تُرسل إليك خدمات أخرى أحداثاً (Webhooks)
- تقسّم العمل بين فريق الواجهة الأمامية وفريق الخادم
REST هو الأسلوب الأكثر شيوعا، لكنه ليس الأسلوب الوحيد. يشرح REST مقابل GraphQL متى تكون نقطة نهاية استعلام واحدة مرنة هي الخيار الأنسب.
صمّم أولاً: الموارد والمسارات
اكتب الأسماء الموجودة في تطبيقك وما يفعله الناس بها. مثال على تطبيق حجوزات بسيط:
| الطريقة | المسار | ما يفعله | رمز النجاح |
|---|---|---|---|
GET | /api/bookings | عرض حجوزات المستخدم الحالي (مع ترقيم الصفحات) | 200 |
POST | /api/bookings | إنشاء حجز | 201 |
GET | /api/bookings/{id} | عرض حجز واحد | 200 |
PATCH | /api/bookings/{id} | تغيير بعض الحقول | 200 |
DELETE | /api/bookings/{id} | إلغاء حجز | 204 |
GET | /api/health | فحص صحة الخدمة للمراقبة | 200 |
هذه المسارات تقابل عمليات الإنشاء والقراءة والتحديث والحذف؛ انظر ما هو CRUD. وهذه قواعد تستحق الالتزام بها:
- أسماء جمع بدون أفعال في الروابط:
/bookingsوليس/getBookings. - تداخل مستوى واحد فقط عندما يوضح الملكية:
/bookings/{id}/notes. - العمليات التي ليست من نوع CRUD يمكن أن تكون موارد فرعية:
POST /bookings/{id}/cancelأوضح من PATCH يحمل معنى خفياً. - تسمية موحدة للحقول، مثل
created_atفي كل مكان.
رموز الحالة والأخطاء
استخدم رموز HTTP القياسية حتى يعرف العميل ما حدث دون تحليل النص:
| الرمز | المعنى | استخدمه عندما |
|---|---|---|
| 200 | نجاح | قراءة أو تحديث ناجح |
| 201 | تم الإنشاء | طلب POST أنشأ شيئاً |
| 204 | لا محتوى | نجاح بدون بيانات لإعادتها |
| 400 | طلب غير صالح | فشل المدخل في التحقق |
| 401 | غير مصرّح | غير مسجل الدخول أو الرمز غير صحيح |
| 403 | ممنوع | مسجل الدخول لكن غير مسموح له |
| 404 | غير موجود | السجل غير موجود، أو يجب ألا يعرف المستخدم بوجوده |
| 409 | تعارض | تكرار، أو الموعد محجوز مسبقاً |
| 429 | طلبات كثيرة جداً | تجاوز حد الطلبات |
| 500 | خطأ في الخادم | حدث عطل من جهتك |
أعِد الأخطاء بشكل JSON موحد واحد، مثلاً {"error": {"code": "slot_taken", "message": "هذا الوقت لم يعد متاحاً."}}، ولا تُضمّن أبداً في الاستجابات تتبّع الأخطاء (stack traces) أو أخطاء قاعدة البيانات.
الخيارات والمفاضلات
| القرار | الخيار البسيط | البديل |
|---|---|---|
| مكان وجود الـ API | مسارات API داخل إطار عمل الويب الخاص بك | خدمة API منفصلة، مفيدة لعدة عملاء أو للغة مختلفة |
| المصادقة | ملفات تعريف الارتباط (cookies) للجلسة في تطبيق الويب الخاص بك | رموز (Bearer tokens أو مفاتيح API) لتطبيقات الموبايل والأطراف الخارجية |
| ترقيم الصفحات | ?page=2&limit=20 | بالمؤشر (?after=...)، وهو أثبت للقوائم الكبيرة والمتغيرة |
| الإصدارات | لا شيء حتى يكون لديك مستخدمون خارجيون | /v1/ في المسار بعد أن يعتمد عليه آخرون |
| التوثيق | ملف README يسرد المسارات | مواصفات OpenAPI، تستطيع الأدوات تحويلها إلى توثيق تفاعلي وشيفرة عملاء |
خطوة بخطوة
- اكتب الموارد والمسارات كما سبق، مع تحديد من يحق له استدعاء كل مسار.
- صمّم البيانات في قاعدة بياناتك بالحقول والعلاقات التي تحتاجها.
- ابنِ مسارات القراءة أولاً، ثم الإنشاء والتحديث والحذف.
- تحقق من المدخلات في كل عملية كتابة باستخدام مكتبة مخططات (schema): الحقول المطلوبة والأنواع والأطوال والقيم المسموحة. وارفض الحقول غير المعروفة.
- أضف المصادقة، ثم التفويض لكل سجل: فتح
/bookings/42يجب أن يتحقق من أن الحجز 42 يخص المستخدم الحالي، لا أن يكتفي بالتحقق من أن أحداً قد سجّل الدخول. - قسّم كل قائمة إلى صفحات وحدّد الحد الأقصى لحجم الصفحة.
- حدّد عدد الطلبات لتسجيل الدخول والمسارات المكلفة. انظر حدود الطلبات.
- اضبط CORS فقط إذا كان يجب أن تستدعي المتصفحات على نطاقات أخرى الـ API، واذكر تلك المصادر بشكل صريح. يشرح كيفية إصلاح أخطاء CORS الأخطاء التي ستراها.
- اكتب التوثيق والاختبارات لكل مسار، بما في ذلك حالات الفشل.
- انشر مع وضع الأسرار في متغيرات البيئة، و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 الخلفية في الوثائق طلبا جاهزا: سمِّ الإطار والمسارات، واطلب أخطاء JSON واضحة، واحتفظ بالأسرار في متغيرات البيئة، وأدرج Dockerfile. تُنشر الخلفيات المبنية على الحاويات بلغة Node وPython وC# وJava وغيرها عبر Dockerfile، ويتولى Mythex النشر من Publish (واجهات API الخلفية). يمكن للمشروع أن يشغّل موقعا وخادم API جنبا إلى جنب، ويمكنك التبديل بينهما في المعاينة. احفظ المفاتيح كأسرار للمشروع، وإذا كانت واجهتك تحتاج إلى قاعدة بيانات فاطلبها في المحادثة: يمكن لكل مشروع أن يملك قاعدة بيانات Postgres خاصة به، متاحة في كل خطة. يستطيع الوكيل اختبار الواجهة نيابة عنك، وفي خطة Pro يمكنك تعديل الكود بنفسك في المحرر والطرفية، أو الإبقاء عليه في مزامنة ثنائية الاتجاه مع GitHub. وللأعمال المجدولة حول واجهتك، اطلع على كيفية تشغيل المهام الخلفية.
الأسئلة
ما هو REST API؟
هو طريقة تتيح للبرامج التعامل مع بيانات تطبيقك عبر HTTP. كل نوع من البيانات يُعد مورداً له رابط خاص به، مثل /orders، والطرق القياسية تعمل عليه: GET للقراءة، وPOST للإنشاء، وPATCH أو PUT للتحديث، وDELETE للحذف. وعادةً ما تُرسل البيانات بصيغة JSON.
بأي لغة برمجة يجب أن أبني REST API؟
استخدم ما يستطيع فريقك صيانته. Node.js مع Express أو Fastify، وPython مع FastAPI، وإطارات C# أو Java كلها خيارات جيدة. قواعد التصميم الخاصة بالمسارات ورموز الحالة والتحقق والمصادقة أهم من اللغة نفسها. يشغّل Mythex واجهات API بلغة Node أو Python أو Java أو C#، أو بأي شيء يعمل كخادم ويب من Dockerfile، لذا يمكنك اختيار ما تعرفه.
كيف أؤمّن REST API؟
اشترط المصادقة على كل مسار غير عام، وتحقق على الخادم من أن المستخدم مسموح له بالوصول إلى كل سجل بعينه، وتحقق من كل المدخلات، واستخدم HTTPS، وحدّد عدد الطلبات، واحفظ الأسرار في متغيرات البيئة. ولا تثق أبداً بالمعرّفات أو الأدوار التي يرسلها العميل.
هل أحتاج إلى خادم خلفي منفصل لـ REST API؟
ليس دائما. تستطيع أطر مثل Next.js تقديم مسارات API إلى جانب الصفحات. وتكون الخدمة المنفصلة منطقية عندما يستخدمها عدة عملاء (الويب، والهاتف، والشركاء)، أو عندما تحتاج إلى لغة أو توسّع خاص بها. في Mythex يمكن أن يعيش الموقع وواجهة API في مشروع واحد وينشران معا.