ما هي REST API؟ شرح للمبتدئين من HTTP وJSON إلى أول تكامل

إذا بدأت تطوير تطبيق حقيقي ستقابل كلمة API بسرعة: تطبيق موبايل يحتاج بيانات من الخادم، واجهة ويب تريد تسجيل مستخدم، أو نظام يحتاج إرسال طلب إلى خدمة أخرى. ومن أكثر الأساليب انتشارًا لبناء هذه الواجهات مفهوم REST API.

هذا الشرح لا يفترض معرفة مسبقة. سنبدأ من معنى API، ثم نفهم HTTP وJSON والـMethods والـStatus Codes، ونرى شكل الطلب والاستجابة في مثال عملي.

ما هي API أصلًا؟

API هي واجهة تسمح لبرنامج بالتعامل مع برنامج أو خدمة أخرى من خلال عقد معروف. بدل أن يعرف التطبيق كيف تُخزن البيانات داخليًا، يرسل طلبًا متفقًا عليه ويحصل على استجابة متفق عليها.

مثلًا، واجهة إدارة المهام قد توفر عمليات لعرض المهام وإضافة مهمة وتعديلها وحذفها، بينما تخفي تفاصيل قاعدة البيانات والتنفيذ الداخلي.

ما معنى REST؟

REST هو أسلوب معماري لبناء أنظمة موزعة حول موارد Resources يتم التعامل معها عبر واجهة موحدة. في تطبيقات الويب يُستخدم HTTP عادة لتنفيذ هذا الأسلوب.

عمليًا ستجد API تعرض عناوين مثل:

GET /api/tasks
GET /api/tasks/42
POST /api/tasks
PUT /api/tasks/42
DELETE /api/tasks/42

المسار يصف المورد، والـHTTP Method يصف نوع العملية.

أهم HTTP Methods للمبتدئ

هذه معانٍ شائعة وليست دعوة لاستخدام أي Method بشكل عشوائي. تصميم العقد يجب أن يكون واضحًا ومتسقًا عبر النظام.

ما هو JSON؟

JSON صيغة نصية شائعة لتبادل البيانات. قد يرسل العميل طلب إنشاء مهمة بهذا الشكل:

{
  "title": "Review pull request",
  "done": false
}

ويرد الخادم مثلًا:

{
  "id": 42,
  "title": "Review pull request",
  "done": false
}

JSON ليس قاعدة بيانات ولا API بحد ذاته؛ هو فقط أحد الأشكال التي يمكن نقل البيانات بها.

ما الذي يوجد داخل HTTP Request؟

الطلب عادة يتكون من Method وURL وHeaders، وقد يحتوي على Body. من الـHeaders الشائعة Content-Type لتحديد نوع البيانات وAuthorization عندما تحتاج الخدمة إلى هوية أو token.

أما الاستجابة فتحتوي على Status Code وHeaders وقد تحتوي على Body بالبيانات أو تفاصيل الخطأ.

أهم Status Codes

• 200 OK: الطلب نجح بصورة عامة.
• 201 Created: تم إنشاء مورد جديد.
• 204 No Content: نجحت العملية ولا توجد بيانات مطلوبة في الـBody.
• 400 Bad Request: الطلب غير صالح أو المدخلات غير مقبولة.
• 401 Unauthorized: يلزم Authentication أو بيانات الاعتماد غير صالحة.
• 403 Forbidden: الهوية معروفة لكن العملية غير مسموحة.
• 404 Not Found: المورد المطلوب غير موجود.
• 409 Conflict: الطلب يتعارض مع الحالة الحالية للمورد.
• 500 Internal Server Error: حدث خطأ غير متوقع في الخادم.

اختيار الكود الصحيح يساعد العميل على التعامل مع النتيجة بدون محاولة فهم رسالة نصية مختلفة في كل endpoint.

مثال كامل: إضافة مهمة

يرسل التطبيق:

POST /api/tasks
Content-Type: application/json

{
  "title": "Write API tests"
}

يتحقق الخادم من البيانات، ينشئ السجل، ثم قد يعيد:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 43,
  "title": "Write API tests",
  "done": false
}

إذا كان العنوان فارغًا، يمكن أن يعود 400 مع تفاصيل تساعد الواجهة على إظهار الخطأ للمستخدم.

أين تدخل قاعدة البيانات؟

الـAPI ليست قاعدة البيانات. Endpoint قد يقرأ من SQL، أو يتعامل مع Cache، أو يستدعي خدمة أخرى، أو يجمع عدة مصادر. العميل لا يحتاج معرفة هذه التفاصيل ما دام العقد ثابتًا.

هذه الطبقة الفاصلة تسمح بتغيير التنفيذ الداخلي بدون كسر كل العملاء، بشرط الحفاظ على contract متوافق.

Authentication وAuthorization

Authentication يجيب: من أنت؟ أما Authorization فيجيب: ماذا يُسمح لك أن تفعل؟ قد يكون المستخدم مسجلًا بنجاح لكنه لا يملك صلاحية حذف مورد معين.

لا ترسل كلمات المرور أو الأسرار داخل URL، ولا تخزن tokens الحساسة بطريقة غير آمنة في التطبيقات. الأمان جزء من تصميم الـAPI وليس خطوة بعد الانتهاء.

كيف تختبر API؟

يمكن استخدام أدوات مثل curl أو عميل API أو اختبارات آلية. المهم أن تختبر Happy Path وحالات الخطأ والمدخلات غير الصالحة والصلاحيات.

وعند وضع المشروع في CI يمكن تشغيل اختبارات الـAPI تلقائيًا مع كل Pull Request. اقرأ شرح GitHub Actions وCI/CD لفهم مكان هذه الاختبارات في دورة التطوير.

REST API جيدة ليست مجرد URLs

الجودة تأتي من اتساق الأسماء، validation واضح، errors قابلة للفهم، versioning عند الحاجة، documentation، security، ومراعاة التوافق مع العملاء الحاليين. لا تجعل كل endpoint يخترع طريقة مختلفة للاستجابة.

أخطاء شائعة

• استخدام GET لتغيير البيانات.
• إرجاع 200 لكل شيء حتى عند وجود خطأ.
• كشف stack traces أو أسرار في رسائل الخطأ.
• ربط شكل قاعدة البيانات مباشرة بالعقد الخارجي بدون حاجة.
• تغيير response موجود بدون التفكير في التطبيقات التي تعتمد عليه.
• عدم وجود validation أو اختبارات لحالات الصلاحيات.

من أين تبدأ عمليًا؟

1. افهم HTTP وMethods وStatus Codes.
2. ابنِ API صغيرة لمورد واحد مثل Tasks.
3. أضف validation وقاعدة بيانات.
4. أضف Authentication بعد فهم الأساس.
5. اكتب tests للسيناريوهات المهمة.
6. وثق الـendpoints والمدخلات والاستجابات.

إذا كنت ما زلت تحدد هل هذا المسار يناسبك، راجع دليل Frontend وBackend وFull Stack.

الخلاصة

REST API هي طريقة منظمة تجعل التطبيقات تتواصل عبر موارد وطلبات HTTP واضحة. ابدأ بفهم Request وResponse وMethods وStatus Codes وJSON، ثم انتقل إلى قواعد البيانات والصلاحيات والاختبارات. فهم هذه الأساسيات أهم من حفظ إطار عمل بعينه.