دليل تصميم API: بناء واجهات برمجية يحبها المستخدمون

واجهة برمجية سيئة التصميم هي ضريبة على كل مطور يستخدمها. واجهة برمجية مصممة جيداً تبدو طبيعية وتتسع بدون كسر. إليك كيفية بناء الأخيرة.

مبادئ REST API

1. استخدم الأسماء وليس الأفعال

سيء:

```

GET /api/getUsers

POST /api/createUser

DELETE /api/deleteUserById?id=123

```

جيد:

```

GET /api/users

POST /api/users

DELETE /api/users/123

```

2. رموز حالة HTTP مهمة

لا تستخدم 200 لكل شيء:

```

200 OK → نجح الطلب

201 Created → تم إنشاء المورد

204 No Content → نجح، لا جسم الرد

400 Bad Request → خطأ العميل

401 Unauthorized → المصادقة مطلوبة

403 Forbidden → غير مسموح

404 Not Found → المورد غير موجود

500 Server Error → خطأ على جانبنا

```

3. صيغة رد ثابتة

كل رد يجب أن يتبع نفس الهيكل:

```json

{

"success": true,

"data": { "id": 123, "name": "أحمد" }

}

```

4. Pagination للقوائم

لا تُرجع ملايين السجلات فوراً:

```

GET /api/users?page=1&limit=50

```

5. التصفية والفرز

دع العملاء يحددون البيانات التي يريدونها:

```

GET /api/users?status=active&sort=created_at:desc

```

الخلاصة

واجهة برمجية جيدة التصميم تتسع وتبدو طبيعية. نحن نبني واجهات برمجية رائعة في مزناة.