How to Test REST APIs in Your Browser — A Developer's Guide

ما هو اختبار واجهات برمجة التطبيقات؟

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

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

شرح طرق HTTP

تستخدم واجهات REST طرق HTTP القياسية للدلالة على العملية المنفَّذة على مورد. فيما يلي مرجع سريع:

الطريقة	الغرض	يحتوي على جسم
GET	استرجاع مورد أو مجموعة	لا
POST	إنشاء مورد جديد	نعم
PUT	استبدال المورد بالكامل	نعم
PATCH	تحديث جزئي للمورد	نعم
DELETE	حذف مورد	نادرًا

تمييز مهم: PUT يستبدل المورد كاملًا؛ أي حقول لا ترسلها قد تُزال. أما PATCH فيحدّث الحقول الواردة في جسم الطلب فقط. غالبًا ما تستخدم واجهات تقبل التعديل PATCH للتحديث الجزئي وPUT للاستبدال الكامل.

كيفية اختبار واجهات برمجة التطبيقات من المتصفح

لا يلزمك تثبيت Postman أو حفظ خيارات سطر أوامر cURL لاختبار واجهة. يتيح لك مستكشف واجهة برمجة التطبيقات على JSONTech.net إرسال الطلبات في وضع المتصفح للواجهات التي تسمح بـ CORS، أو التحويل إلى وضع الوكيل عندما يحجب المتصفح الطلب. الخطوات كالتالي:

1. افتح أداة مستكشف واجهة برمجة التطبيقات.
2. اختر طريقة HTTP (GET أو POST أو PUT أو PATCH أو DELETE) من القائمة المنسدلة.
3. أدخل عنوان URL للنقطة الطرفية. مثال: https://jsonplaceholder.typicode.com/posts/1
4. أضف الرؤوس الضرورية (مثل Content-Type أو Authorization).
5. إذا كانت الطريقة تتطلب جسمًا (POST أو PUT أو PATCH)، اكتب حمولة JSON في محرّر الجسم.
6. اضغط إرسال وراجع الاستجابة: رمز الحالة، الرؤوس، وجسم JSON المنسّق.

إذا أظهر المتصفح خطأ CORS، فحوّل مستكشف واجهة برمجة التطبيقات إلى وضع الوكيل. عندها يمر الطلب الحقيقي عبر البنية الطرفية لـ JSONTech لتتمكن من متابعة الاختبار من الصفحة نفسها.

مثال: جلب منشور

GET https://jsonplaceholder.typicode.com/posts/1

Response (200 OK):
{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\\nsuscipit recusandae consequuntur..."
}

مثال: إنشاء منشور

POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{
  "title": "My New Post",
  "body": "This is the content of my post.",
  "userId": 1
}

Response (201 Created):
{
  "id": 101,
  "title": "My New Post",
  "body": "This is the content of my post.",
  "userId": 1
}

فهم رؤوس الطلب

تحمل الرؤوس بيانات وصفية عن الطلب؛ تُعلِم الخادم بالتنسيق المتوقع، بهوية المرسل، وسلوك الاتصال. فيما يلي الأكثر شيوعًا:

الرأس	الغرض	مثال للقيمة
Content-Type	تنسيق جسم الطلب	application/json
Accept	التنسيق المطلوب في الاستجابة	application/json
Authorization	بيانات الاعتماد للمصادقة	Bearer eyJhbGciOi...
Cache-Control	توجيهات التخزين المؤقت	no-cache
User-Agent	تعريف تطبيق العميل	MyApp/1.0

إغفال Content-Type: application/json في طلبات POST/PUT من أشهر أسباب إرجاع واجهات برمجة التطبيقات لرمز 400 Bad Request؛ فبدون ذلك لا يعرف الخادم كيفية تحليل الجسم.

طرق المصادقة

تفرض معظم واجهات الإنتاج مصادقةً. ثلاثة أنماط شائعة:

رمز الحامل (Bearer Token / JWT)

الأكثر شيوعًا في الواجهات الحديثة. تُدرج الرمز في رأس Authorization:

{
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "Content-Type": "application/json"
  }
}

المصادقة الأساسية (Basic Auth)

تُرمّز اسم المستخدم وكلمة المرور كسلسلة Base64. بسيطة، لكنها آمنة فقط فوق HTTPS:

{
  "headers": {
    "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=",
    "Content-Type": "application/json"
  }
}

مفتاح API

تستخدم بعض الواجهات رأسًا مخصصًا أو معلَمة استعلام لمفتاح ثابت:

// As a header
{
  "headers": {
    "X-API-Key": "sk_live_abc123def456"
  }
}

// As a query parameter
GET https://api.example.com/data?api_key=sk_live_abc123def456

قراءة استجابات واجهة برمجة التطبيقات

بعد إرسال الطلب، تبيّن الاستجابة ما الذي حدث. ركّز على ثلاثة عناصر: رمز الحالة، رؤوس الاستجابة، والجسم.

رموز الحالة

الرمز	المعنى	متى تظهر
200	نجاح	طلب GET أو PUT أو PATCH أو DELETE ناجح
201	تم الإنشاء	طلب POST ناجح أنشأ موردًا
400	طلب غير صالح	JSON غير صالح، حقول ناقصة، أو أنواع خاطئة
401	غير مصرّح	رمز مصادقة مفقود أو منتهٍ الصلاحية
403	ممنوع	اعتماد صالح لكن بلا صلاحية كافية
404	غير موجود	النقطة الطرفية أو المورد غير موجود
500	خطأ داخلي في الخادم	عطل في جانب الخادم

رؤوس الاستجابة

انتبه لرؤوس مثل Content-Type (لتأكيد تنسيق الاستجابة)، وX-RateLimit-Remaining (عدد الطلبات المتبقية)، وRetry-After (متى تعيد المحاولة بعد تجاوز حد المعدّل).

جسم JSON

في الجسم تكمن البيانات. غالبًا تلفّ واجهة مصممة جيدًا النتيجة بهيكل ثابت:

{
  "data": {
    "id": 42,
    "name": "Widget",
    "price": 9.99
  },
  "meta": {
    "request_id": "req_8f3a2b"
  }
}

عند الفشل يُعاد كائن خطأ بدل كائن البيانات. تحقّق أولًا من رمز الحالة، ثم حلّل الجسم وفقًا لذلك.

CORS: ما المقصود به ولماذا تظهر أخطاء؟

مشاركة الموارد بين المصادر (CORS) آلية أمان في المتصفح. عندما يحاول JavaScript يعمل على localhost:3000 الاتصال بواجهة على api.example.com، يحجب المتصفح الطلب ما لم يصرّح الخادم بذلك عبر رؤوس CORS.

مثال شائع لرسالة الخطأ:

Access to fetch at 'https://api.example.com/data' from origin
'http://localhost:3000' has been blocked by CORS policy: No
'Access-Control-Allow-Origin' header is present on the requested resource.

هذا ليس عيبًا في منطق تطبيقك، بل تنفيذ للسياسة في المتصفح، والمعالجة من جهة الخادم. حلول عملية:

• اطلب من مالك الواجهة إضافة أصل تطبيقك إلى رأس Access-Control-Allow-Origin.
• استخدم وسيطًا (proxy) — مرّر الطلبات عبر خادمك الخلفي (مثل مسار API في Next.js أو خادم Express بسيط) لتجاوز قيد الأصول المختلفة.
• استخدم أداة متصفّح مع خيار الوكيل مثل مستكشف واجهة برمجة التطبيقات. ابدأ بوضع المتصفح مع الواجهات المفتوحة، وانتقل إلى وضع الوكيل عندما تحتاج أن يعيد JSONTech تمرير الطلب لأغراض الاختبار.

CORS يخص المتصفحات فقط. أدوات مثل cURL وPostman والشيفرة على الخادم لا تخضع لقيود CORS لأنها لا تعمل داخل «رمل» المتصفح.

أخطاء شائعة في اختبار واجهات برمجة التطبيقات

أخطاء يقع فيها المطوّرون — من المبتدئين إلى من يعملون على واجهات غير مألوفة:

1. نسيان رأس Content-Type. إرسال JSON بدون Content-Type: application/json يدفع كثيرًا من الخوادم لرفض الطلب أو تحليله خطأ.
2. استخدام GET بدل POST. لا يجب أن يحتوي GET على جسم؛ لإرسال بيانات استخدم POST أو PUT أو PATCH.
3. تجاهل رموز الحالة. استجابة 200 مع رسالة خطأ في الجسم ليست نجاحًا حقيقيًا؛ راجع رمز HTTP الفعلي.
4. تضمين بيانات اعتماد في عنوان URL. تجنّب وضع مفاتيح API أو رموز في سلسلة الاستعلام إن وُجدت رؤوس بديلة؛ فالعناوين تُسجَّل في السجلات وتاريخ المتصفح ورؤوس الإحالة.
5. اختبار المسار السعيد فقط. جرّب JSON تالفًا، أجسامًا فارغة، حقولًا مطلوبة ناقصة، ورموزًا غير صالحة لمعرفة سلوك الواجهة عند الخطأ.
6. عدم مراقبة حدود المعدّل. كثير من الواجهات يعيد 429 عند التجاوز؛ راقب X-RateLimit-Remaining مبكرًا.
7. خلط أخطاء CORS بأخطاء الخادم. خطأ CORS يعني أن المتصفح حجب الطلب؛ وقد يكون الخادم قد أجاب بنجاح دون أن يعرض المتصفح النتيجة.

جرّب بنفسك

هل تريد اختبار واجهة الآن؟ افتح مستكشف واجهة برمجة التطبيقات وأرسل طلب GET إلى https://jsonplaceholder.typicode.com/users/1. ستظهر الاستجابة كاملة — رمز الحالة، الرؤوس، وجسم JSON منسّق — وإذا حُجبت واجهة أخرى بسبب CORS يمكنك إعادة المحاولة في وضع الوكيل.

بلا تنزيلات ولا تسجيل ولا إعدادات معقّدة. اختر الطريقة، أدخل عنوان URL، ثم اضغط إرسال.