نقاط نهاية REST API
Caution
صفحة عرض توضيحي - هذه صفحة عرض توضيحي تبرز ميزة التوثيق متعدد التبويبات. المحتوى هنا لأغراض التوضيح فقط.
يوفر REST API لدينا نقاط نهاية للوصول إلى البيانات والتعامل معها. تعيد جميع نقاط النهاية البيانات بصيغة JSON.
عنوان URL الأساسي
يجب توجيه جميع طلبات API إلى عنوان URL الأساسي التالي:
https://api.example.com/v1نقاط نهاية المستخدمين
جلب جميع المستخدمين
GET /usersتعيد قائمة بجميع المستخدمين. تدعم معاملات ترقيم الصفحات.
معاملات الاستعلام:
| المعامل | النوع | الوصف |
|---|---|---|
| page | integer | رقم الصفحة (الافتراضي: 1) |
| limit | integer | عدد السجلات في الصفحة (الافتراضي: 50، الحد الأقصى: 100) |
| sort | string | الحقل الذي يُرتَّب حسبه (مثل “name” أو “created_at”) |
الاستجابة:
{ "data": [ { "id": "user_123", "name": "John Doe", "created_at": "2023-01-15T08:30:00Z" }, // More users... ], "meta": { "total": 250, "page": 1, "limit": 50 }}جلب مستخدم بالمعرّف
GET /users/{id}تعيد مستخدمًا واحدًا بحسب المعرّف.
الاستجابة:
{ "data": { "id": "user_123", "name": "John Doe", "created_at": "2023-01-15T08:30:00Z", "profile": { "bio": "Software developer", "location": "New York", "avatar_url": "https://example.com/avatars/john.jpg" } }}نقاط نهاية المنتجات
جلب جميع المنتجات
GET /productsتعيد قائمة بجميع المنتجات. تدعم التصفية وترقيم الصفحات.
معاملات الاستعلام:
| المعامل | النوع | الوصف |
|---|---|---|
| category | string | تصفية حسب الفئة |
| min_price | number | تصفية حسب الحد الأدنى للسعر |
| max_price | number | تصفية حسب الحد الأقصى للسعر |
| page | integer | رقم الصفحة (الافتراضي: 1) |
| limit | integer | عدد السجلات في الصفحة (الافتراضي: 50، الحد الأقصى: 100) |
الاستجابة:
{ "data": [ { "id": "prod_123", "name": "Example Product", "description": "This is an example product", "price": 49.99, "category": "electronics" }, // More products... ], "meta": { "total": 350, "page": 1, "limit": 50 }}معالجة الأخطاء
تتبع جميع نقاط النهاية رموز حالة HTTP القياسية، وتتضمن رسائل خطأ مفصّلة عند الاقتضاء:
| رمز الحالة | الوصف |
|---|---|
| 200 | OK، نجح الطلب |
| 400 | Bad Request، معاملات غير صالحة |
| 401 | Unauthorized، المصادقة مطلوبة |
| 403 | Forbidden، الصلاحيات غير كافية |
| 404 | Not Found، المورد غير موجود |
| 429 | Too Many Requests، تم تجاوز حد المعدل |
| 500 | Internal Server Error، حدث خطأ في الخادم |
تتضمن استجابات الخطأ رسالة توضح سبب الخلل:
{ "error": { "code": "invalid_parameter", "message": "The parameter 'email' is not a valid email address", "request_id": "req_abc123" }}