لماذا يهم التصميم API
API مُصممة جيدًا هي منتج في حد ذاتها. تؤثر على تجربة المطورين، وسرعة التكامل، ومتانة الطويلة الأجل. إليك المبادئ التي نتبعها في DevFlow.
مبادئ التصميم URL
تسمية الموارد
استخدم اسماء الأشياء، وليست الأفعال. يحدد الطريقة HTTP الفعل.
# جيد
GET /api/v1/users
POST /api/v1/users
GET /api/v1/users/:id
# سيئ
GET /api/v1/getUsers
POST /api/v1/createUserتنسيق الإجابة المتسقة
يجب أن يعود كل نقطة الوصول API بنفس التنسيق حتى يعرف المستهلك ماذا ينتظره.
{
"status": "success",
"data": { "id": "user-123", "name": "John Doe" },
"pagination": { "page": 2, "limit": 20, "total": 150 }
}كودات HTTP
| كود | استخدام |
|---|---|
| 200 | GET، PUT، PATCH الناجحة |
| 201 | POST الناجحة (المورد خلق) |
| 204 | DELETE الناجحة (لا يوجد محتوى) |
| 400 | فشل التحقق |
| 401 | تطلبت الحماية |
| 403 | السماحات غير كافية |
| 404 | المورد غير موجود |
| 429 | تجاوز الحد الأقصى للسرعة |
أنماط التصفية
# مبادئ السهم (الموصى به للبيانات الكبيرة)
GET /api/v1/posts?cursor=eyJpZCI6MTAwfQ&limit=20
# مبادئ التصفية (أسهل، جيد للبيانات الصغيرة)
GET /api/v1/posts?page=3&limit=20الاستنتاج
تصميم API جيد هو استثمار يعود الأرباح في مدة المنتج. اتبع المبادئ، كن متسقًا، وادوكل كل شيء.
