مقدمة إلى API: فهم "الحوار بين البرامج" من الصفر

🎯 السؤال الأساسي

ما هو API؟ هذا مثل السؤال: كيف تصمم قائمة المطعم بحيث يفهمها الزبون من النظرة الأولى؟ كيف يسجل النادل الطلب دون أخطاء؟ API يحل مشكلة "كيف تتحاور البرامج مع بعضها". أنت تستخدم API منذ أول يوم كتبت فيه كودًا، ربما فقط لم تدرك ذلك.

---

0. ثلاث حيرات شائعة للمبتدئين

الحيرة الأولى: هل API شيء معقد جدًا؟

كثير من الناس عندما يسمعون API، يعتقدون أنه مفهوم لا يفهمه إلا المهندسون الكبار. في الواقع أنت استخدمت API منذ فترة طويلة:

len("hello")        # هذا API توفره Python
open("file.txt")    # هذا أيضًا API
requests.get(url)   # وهذا أيضًا API

الحيرة الثانية: ما الفرق بين Web API والـ API العادي؟

النوع	كائن الاستدعاء	طريقة التواصل	السيناريو النموذجي
دالة API	كود محلي	استدعاء دالة	len(), open()
API نظام التشغيل	نظام التشغيل	استدعاء نظام	قراءة وكتابة الملفات، إنشاء عمليات
Web API	خادم بعيد	طلب HTTP	استدعاء نموذج ذكاء اصطناعي، الحصول على الطقس

الحيرة الثالثة: هل أستخدم HTTP أم SDK؟

# طريقة HTTP: تعالج كل التفاصيل بنفسك
import requests
response = requests.post(
    "https://api.deepseek.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-xxx"},
    json={"model": "deepseek-chat", "messages": [...]}
)
result = response.json()["choices"][0]["message"]["content"]

# طريقة SDK: الوكيل يعالجها نيابة عنك
from openai import OpenAI
client = OpenAI(api_key="sk-xxx")
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[...]
)
result = response.choices[0].message.content

---

1. جوهر API: القابس والمقبس

API (Application Programming Interface، واجهة برمجة التطبيقات) هو "اتفاقية الحوار بين البرامج".

1.1 التشبيه بالأجهزة الكهربائية

المفهوم	تشبيه الأجهزة الكهربائية	مقابل API
الواجهة	شكل المقبس	توقيع الدالة / URL
المدخلات	دخول التيار	معاملات الدالة / جسم الطلب
المخرجات	عمل الجهاز	قيمة الإرجاع / جسم الاستجابة

1.2 مقارنة أشكال API الثلاثة

TargetLocal code library

CommunicationFunction call

LatencyNanoseconds

Typical scenariosData processing, file operations

Function API example

len("hello")           # returns 5
max([1, 5, 3])         # returns 5
open("file.txt").read() # reads a file

1.3 الفرق بين دالة API و HTTP API

كثير من المبتدئين يحتارون: ما الفرق بين دالة API و HTTP API؟ كيف نفرق بينهما عند قراءة التوثيق؟

📚 Function API vs HTTP APILocal calls vs network requests: how should you read the docs?

📦Function API

Call styleDirect function call

ParametersArguments inside parentheses

Return valueReturn value directly

Error handlingException or return value

Python example

# Call a built-in function
length = len("hello")      # returns 5

# Call a library function
import math
result = math.sqrt(16)     # returns 4.0

# Call a custom function
def add(a, b):
    return a + b
sum = add(3, 5)            # returns 8

VS

🌐HTTP API

Call styleNetwork request

ParametersURL / body / headers

Return valueJSON/XML response

Error handlingStatus code checks

HTTP request example

POST /v1/chat/completions HTTP/1.1
Host: api.deepseek.com
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}

Core point:A function API works locally; an HTTP API communicates remotely. Function docs focus on parameters and return values, while HTTP API docs focus on endpoint, authentication, and request/response formats.

1.4 كيفية قراءة أنواع مختلفة من توثيق API

عند مواجهة أنواع مختلفة من توثيق API، تختلف نقاط التركيز:

📋 How to Read Different Doc TypesFunction docs, REST API docs, and SDK docs each emphasize different things

Doc typeFunction docs

Best forUsing standard library or third-party functions

Difficulty⭐⭐

🔍 What to focus on

Function signatureParameter typesReturn valueExceptionsExample code

📝Doc example

### json.loads(s, *, cls=None, object_hook=None...)

Parse a JSON string into a Python object.

**Parameters:**
- s (str): JSON string to parse
- cls (JSONDecoder): Custom decoder class
- object_hook (callable): Optional conversion function

**Returns:**
- dict | list: Parsed Python object

**Raises:**
- JSONDecodeError: The string is invalid JSON

**Example:**
>>> import json
>>> json.loads('{"name": "Alice"}')
{'name': 'Alice'}

💡Reading tips

• Read the function signature first to see what parameters are needed.
• Check parameter types and whether each parameter is required.
• Check the return type so later code can handle it correctly.
• Notice possible exceptions and prepare error handling.

📊Quick comparison of three doc types

Item

Function docs

REST API docs

SDK docs

Core focus

Parameters, return values

Endpoint, request body

Initialization, method chain

Code example

Function call

HTTP request

Object method

Error handling

Exceptions/return values

Status codes

Exception objects

Read first

Function signature

Base URL + Auth

Quick Start

Reading advice:For function docs, read the signature. For API docs, read the request format. For SDK docs, read examples first. When stuck, look for Quick Start or Getting Started.

---

2. استدعاء API كامل

👇 جرب بنفسك: انقر على الزر أدناه، ولاحظ تدفق طلب-استجابة API كامل:

API Request Demo

// Click a command below to simulate API requests

> ▋

💻ClientSends request

Waiting for request...

HTTP Request→

🖥️ServerHandles request

Waiting...

HTTP Response←

📦ResponseReturns result

Waiting for response...

💡 Click a command button to observe a complete API request-response flow.

2.1 المراحل الأربع لاستدعاء API

المرحلة	ماذا يحدث	تشبيه الأجهزة الكهربائية
الطلب	العميل يرسل طلبًا للخادم	الضغط على المفتاح
النقل	الطلب ينتقل عبر الشبكة للخادم	التيار يمر عبر الأسلاك
المعالجة	الخادم يعالج الطلب ويعيد البيانات	الجهاز يبدأ العمل
الاستجابة	العميل يستقبل ويعالج النتيجة	المصباح يضيء

2.2 تشبيه المطعم

دور المطعم	مقابل API	الوصف
القائمة	توثيق API	تخبرك ما هي "الأطباق" المتاحة للطلب
النادل	بروتوكول HTTP	"طريقة حوار" موحدة
المطبخ	الخادم	يعالج الطلبات حسب "الطلبات"
تقديم الطبق	الاستجابة	إعادة النتيجة إلى "الزبون"

---

3. طرق HTTP: هل أنت "تسأل" أم "تفعل"؟

عند استدعاء Web API، تحتاج لإخبار الخادم ماذا تريد أن تفعل. هذا هو أصل طرق HTTP.

3.1 الفهم من خلال طلب الطعام في المطعم

السيناريو	ماذا تقول في الواقع؟	طريقة HTTP المقابلة
تريد معرفة ما هو متاح اليوم	"نادل، أرني القائمة"	GET - "سؤال" خالص، لا يغير البيانات
تريد طلب دجاج كونغ باو	"أعطني دجاج كونغ باو"	POST - "فعل" شيء، إنشاء بيانات
تريد تغيير طبق	"غير دجاج كونغ باو إلى لحم حلو وحامض"	PUT - استبدال البيانات
تريد تغيير النكهة	"دجاج كونغ باو بدون فول سوداني"	PATCH - تعديل جزئي
لا تريده بعد الآن	"لا يهم، ألغِ ذلك الطبق"	DELETE - حذف البيانات

get

Read

Query data

Idempotent

post

Create

Add data

Not idempotent

put

Full update

Replace resource

Idempotent

patch

Partial update

Modify fields

Not idempotent

delete

Delete

Remove resource

Idempotent

getRead - Query data

Fetch resources from the server without changing data

Restaurant analogy:"Waiter, show me the menu"

GET /api/users           # fetch user list
GET /api/users/123       # fetch one user
GET /api/products?cat=phone  # query phone products

حول اللامتغيرية

اللامتغيرية: هل نتيجة التنفيذ المتعدد متطابقة؟

• العمليات اللامتغيرة (GET/PUT/DELETE): الطلب 10 مرات والطلب مرة واحدة، النتيجة متطابقة
• العمليات غير اللامتغيرة (POST): الطلب 10 مرات، قد ينشئ 10 طلبات

الحل: عمليات POST تستخدم تحقق بمعرف فريد، لتجنب المعالجة المتكررة.

3.2 جدول مرجعي لطرق HTTP

الطريقة	الاستخدام	اللامتغيرية	الأمان	السيناريو النموذجي
GET	الحصول على مورد	نعم	نعم	استعلام قائمة، عرض تفاصيل
POST	إنشاء مورد	لا	لا	إضافة مستخدم، تقديم طلب
PUT	تحديث كامل	نعم	لا	استبدال ملف المستخدم بالكامل
PATCH	تحديث جزئي	لا	لا	تعديل الاسم المستعار فقط
DELETE	حذف مورد	نعم	لا	حذف مستخدم، إلغاء طلب

---

4. رموز حالة HTTP: ماذا يخبرك الخادم؟

عندما يرد الخادم، يعيد أولاً رمز حالة، ليخبرك ما إذا كان الطلب ناجحًا.

4.1 تصنيف رموز الحالة

2xxSuccess

The request was received, understood, and processed successfully

200 OK201 Created204 No Content

3xxRedirect

More action is needed to complete the request

301 Moved Permanently304 Not Modified307 Temporary Redirect

4xxClient error

The request has an error or cannot be completed

400 Bad Request401 Unauthorized403 Forbidden404 Not Found

5xxServer error

The server failed to handle a valid request

500 Internal Error502 Bad Gateway503 Unavailable

💡Memory tip:2️⃣ Success • 3️⃣ Redirect • 4️⃣ Client error • 5️⃣ Server error

4.2 شرح رموز الحالة الشائعة

رمز الحالة	المعنى	السيناريو النموذجي	معالجة العميل
200 OK	نجاح	تمت معالجة الطلب بشكل طبيعي	عرض البيانات
201 Created	تم الإنشاء بنجاح	طلب POST أنشأ المورد بنجاح	الانتقال للمورد الجديد
400 Bad Request	تنسيق الطلب خاطئ	معاملات مفقودة أو تنسيق خاطئ	فحص المعاملات
401 Unauthorized	غير مصرح	لم يتم تقديم API Key صالح	توجيه المستخدم لتسجيل الدخول
403 Forbidden	لا صلاحية	API Key ليس لديه صلاحية الوصول للمورد	تنبيه بعدم كفاية الصلاحية
404 Not Found	غير موجود	العنوان أو المورد المطلوب غير موجود	فحص URL
429 Too Many Requests	طلبات كثيرة جدًا	تجاوز حد المعدل	إعادة المحاولة لاحقًا
500 Internal Server Error	خطأ في الخادم	مشكلة في الخادم	تنبيه المستخدم بإعادة المحاولة لاحقًا

👇 جرب بنفسك: انقر على الزر أدناه، وتعرف على معاني رموز الحالة الشائعة:

HTTP Status Code Demo

// Click a button to inspect status code meanings

> ▋

✅2xx Success

200OKRequest succeeded

201CreatedResource created

204No ContentSucceeded with no response body

⚠️4xx Client errors

400Bad RequestMalformed request

401UnauthorizedNot authenticated

403ForbiddenNo permission

404Not FoundResource missing

422UnprocessableSemantic validation error

429Too ManyToo many requests

🔴5xx Server errors

500Server ErrorInternal server error

502Bad GatewayGateway error

503UnavailableService unavailable

💡 Click a command button to learn common HTTP status codes.

---

5. HTTP مقابل SDK: تذهب بنفسك أم تدع الوكيل يتولى الأمر؟

5.1 مقارنة طريقتي الاستدعاء

	🏃 HTTP API	🤵 SDK
التشبيه	تذهب بنفسك	الوكيل يتولى الأمر
المزايا	✓ جميع اللغات يمكنها الاستخدام ✓ تحكم كامل في تفاصيل الطلب ✓ لا حاجة لاعتماديات إضافية	✓ كود موجز وسهل القراءة ✓ معالجة تلقائية للمصادقة ✓ إعادة محاولة مدمجة للأخطاء
العيوب	✗ تحتاج معالجة كل التفاصيل ✗ كود طويل وعرضة للأخطاء	✗ تحتاج تثبيت اعتماديات ✗ قد تكون هناك مشاكل في الإصدارات
مثال كود	requests.post(url, json=..., headers={...})	client.chat.completions.create(...)

5.2 كيف تختار؟

السيناريو	الطريقة الموصى بها	السبب
تطوير سريع	SDK	معالجة تلقائية للمصادقة والأخطاء وإعادة المحاولة
تعلم المبادئ	HTTP	فهم الآلية الأساسية
لغة غير مدعومة	HTTP	أي لغة يمكنها الاستخدام
حاجة للتخصيص	HTTP	تحكم مرن في كل تفصيل

💡 نصيحة

استخدم SDK كلما أمكن، اترك الأمور المزعجة للمكتبة، واترك الوقت لنفسك.

---

6. كيف تقرأ توثيق API؟

توثيق API مثل مزيج من دليل التعليمات والقائمة. لست بحاجة لقراءته من البداية للنهاية، فقط تعلم "البحث في القاموس".

6.1 قائمة قراءة التوثيق

عند فتح أي توثيق API (مثل OpenAI أو DeepSeek)، تحتاج فقط للبحث عن هذه الأشياء:

📖API Document Translator

Base URL

https://api.deepseek.com

Endpoint

POST /v1/chat/completions

Headers

Authorization: Bearer sk-xxx
Content-Type: application/json

Body parameters

modelRequiredModel name

messagesRequiredConversation messages

temperatureOptional0-2, default 1

Translate into code

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}]
)

Core idea:When reading docs, find three things: address (Base URL), authentication (Authorization), and parameters.

العنصر	الوصف	مثال
Base URL	العنوان الجذري لـ API	https://api.deepseek.com
Authentication	كيفية إثبات الهوية	Authorization: Bearer sk-xxx
Endpoints	قائمة الواجهات المحددة	/v1/chat/completions
Parameters	المعاملات الإلزامية/الاختيارية	model (إلزامي)، temperature (اختياري)
Response	هيكل البيانات المرتجعة	{"choices": [...]}

6.2 خطوات قراءة التوثيق

1. ابحث عن Base URL - هذه بادئة جميع الطلبات
2. افهم طريقة المصادقة - API Key في Header أم Query؟
3. ابحث عن Endpoint المطلوب - الواجهة المحددة التي ستستدعيها
4. راجع معاملات الطلب - أيها إلزامي؟ أيها اختياري؟
5. افهم تنسيق الإرجاع - كيف يتم تنظيم البيانات؟

---

7. تمرين عملي: محاكاة استدعاء API

الكلام بدون تطبيق لا قيمة له. هنا API محاكي، يمكنك ملء المعاملات وتغيير العنوان كما تشاء، وشاهد ماذا سيحدث.

🧪API PlaygroundTry calls without touching a real server

Endpoint

Method

API Key

Send a request to see the response

Quick tries:

حاول تشغيل السيناريوهات التالية:

• ✅ طلب ناجح: املأ Endpoint و API Key الصحيحين
• ❌ خطأ 401: لا تملأ API Key، وشاهد كيف يرفضك الخادم
• ❌ خطأ 404: املأ عنوانًا غير موجود

---

8. خلاصة

النقاط الأساسية

1. API هو مكبر الصوت، يساعدك في إيصال كلامك لقطعة كود أخرى أو خادم بعيد
2. لقد استخدمت API منذ فترة طويلة، من len() إلى open() كلها API
3. Web API هو قوة خارقة، تتيح لك استدعاء حواسيب عملاقة على بعد آلاف الأميال
4. SDK هو وكيل جيد، استخدم SDK كلما أمكن ولا تذهب بنفسك
5. عند قراءة التوثيق ابحث عن ثلاثة أشياء: العنوان، المصادقة، المعاملات

في عصر البرمجة بالذكاء الاصطناعي، تحتاج فقط لتذكر هذه المفاهيم الأساسية. باقي التفاصيل، سيتولى IDE ومساعد الذكاء الاصطناعي معالجتها.

---

جدول المصطلحات

المصطلح	الاسم الكامل	الشرح
API	Application Programming Interface	واجهة برمجة التطبيقات، تحدد كيفية تفاعل البرمجيات
Web API	-	API مبني على بروتوكول HTTP، للاتصال الشبكي
Endpoint	-	نقطة النهاية، العنوان المحدد لـ API
HTTP	HyperText Transfer Protocol	بروتوكول الاتصال المستخدم في Web API
GET	-	طريقة الحصول على الموارد
POST	-	طريقة تقديم البيانات
SDK	Software Development Kit	مجموعة أدوات تطوير البرمجيات، تغلف استدعاءات API الأساسية
URL	Uniform Resource Locator	عنوان الشبكة لـ API
JSON	JavaScript Object Notation	تنسيق بيانات شائع الاستخدام
Authentication	-	عملية التحقق من الهوية
Status Code	-	رمز الحالة في استجابة HTTP
Request	-	طلب
Response	-	استجابة
Header	-	رأس HTTP، يحتوي معلومات وصفية
Payload	-	البيانات الفعلية للطلب أو الاستجابة
Rate Limit	-	حد المعدل
Idempotent	-	لامتغير، التنفيذ المتعدد يعطي نفس النتيجة
REST	Representational State Transfer	نمط معماري لـ API
RPC	Remote Procedure Call	استدعاء إجراء عن بعد
GraphQL	-	لغة استعلام API
gRPC	-	إطار RPC عالي الأداء من Google