قراءة توثيق الـ API

توثيق الـ API هو أكثر نوع من الإنجليزية التقنية ستصادفه. تعلم قراءته بسرعة يمنحك قوة خارقة.

بنية توثيق الـ API

معظم وثائق الـ API تتبع نمطاً يمكن التنبؤ به:

1. وصف نقطة النهاية (Endpoint Description)

GET /api/users/{id}
Retrieve a user by their unique identifier.

كلمات مفتاحية:

• Retrieve = جلب/استرجاع — تعني الحصول على شيء من الخادم
• Unique identifier = معرف فريد — قيمة تحدد عنصراً واحداً محدداً

2. المعاملات (Parameters)

المعامل	النوع	مطلوب	الوصف
id	string	نعم	المعرف الفريد للمستخدم
fields	string	لا	قائمة حقول مفصولة بفواصل للتضمين

كلمات مفتاحية:

• Required = مطلوب، يجب توفيره
• Optional = اختياري، ليس إلزامياً
• Comma-separated = مفصولة بفواصل

3. الاستجابة (Response)

{
  "id": "user_123",
  "name": "Ahmad",
  "email": "ahmad@example.com",
  "created_at": "2026-01-15T10:30:00Z"
}

4. استجابات الأخطاء (Error Responses)

رمز الحالة	الوصف
200	Success (نجاح) — اكتمل الطلب بنجاح
400	Bad Request (طلب خاطئ) — معاملات غير صالحة
401	Unauthorized (غير مصرح) — المصادقة مطلوبة
404	Not Found (غير موجود) — المورد غير موجود
500	Internal Server Error (خطأ داخلي في الخادم) — حدث خطأ في الخادم

عبارات شائعة في توثيق الـ API

العبارة الإنجليزية	المعنى بالعربية	مثال
"Returns a list of..."	تُرجع قائمة من...	"Returns a list of all active users"
"Accepts the following parameters"	تقبل المعاملات التالية	شائعة في وثائق نقاط POST
"Throws an error if..."	تُلقي خطأ إذا...	"Throws an error if the ID is invalid"
"Deprecated"	مهملة / قديمة	"This endpoint is deprecated. Use v2 instead."
"Rate limited to..."	محدودة بمعدل...	"Rate limited to 100 requests per minute"
"Paginated"	مُرقّمة الصفحات	"Results are paginated with 20 items per page"

استراتيجية القراءة

1. امسح نقطة النهاية — ما طريقة HTTP؟ ما المسار؟
2. تحقق من المعاملات المطلوبة — ما الذي يجب أن ترسله؟
3. انظر إلى مثال الاستجابة — ماذا ستحصل بالمقابل؟
4. لاحظ رموز الأخطاء — ما الذي يمكن أن يخطئ؟

لا تحاول قراءة كل كلمة. امسح بحثاً عما تحتاجه.

:::