أفضل ممارسات تصميم REST API: ابنِ واجهات يحبها المطورون

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

تسمية الموارد

✓ GET /api/users
✓ GET /api/users/42
✓ POST /api/users
✗ GET /api/getUsers
✗ POST /api/createUser

أكواد الحالة

200 — GET/PUT ناجح
201 — POST ناجح
204 — DELETE ناجح
400 — أخطاء التحقق
401 — مصادقة مفقودة
404 — غير موجود
422 — أخطاء دلالية
429 — تجاوز حد المعدل

استجابة خطأ متسقة

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "البيانات غير صالحة.",
        "details": [{"field": "email", "message": "مُستخدم بالفعل"}]
    }
}

ترقيم بالمؤشر

GET /api/posts?cursor=eyJpZCI6MTB9&per_page=20

اتبع هذه الأنماط بشكل متسق ووثّق بـ OpenAPI/Swagger.