ما هي واجهة البرمجة (API) وكيف تعمل؟

العميل والخادم والعقد

العميل يبدأ العمل: JavaScript في المتصفح، أو تطبيق جوال، أو مهمة cron على الخادم، أو واجهة سطر أوامر. الخادم يستمع على الشبكة، يتحقق من هوية المتصل، يتحقق من المدخلات، يتعامل مع قواعد البيانات أو خدمات أخرى، ويردّ باستجابة. الواجهة هي العقد المكتوب — عناوين URL والطرق والترويسات ومخططات الأجسام وأشكال الأخطاء وحدود المعدّل — لا علامة إطار العمل على أي طرف.

قد يكون الطرفان خوادم عملياً: تطبيق Next.js لديك عميل حين يستدعي Stripe، وواجهة Stripe هي العقد الذي تستورده من التوثيق. webhooks تعكس الاتجاه — مزوّد الدفع يصبح العميل الذي يرسل POST إلى نقطة نهايتك — لكن القواعد نفسها: تحقق من التوقيعات، حلّل JSON، أعد رمز حالة ذا معنى، واجعل المعالجات idempotent لأن إعادة المحاولة مضمونة.

نقاط النهاية والموارد

نقطة النهاية هي طريقة HTTP مع مسار (وأحياناً قواعد استعلام) تنفّذ عملية موثّقة واحدة. التصاميم RESTful تربط المسارات بأسماء (/users/42/orders) وتستخدم طرق HTTP للتعبير عن القصد. ليست كل واجهة عامة REST صارمة — مسارات على نمط RPC مثل /createInvoice ما زالت موجودة — لكن عناوين URL متوقعة وحقول JSON متسقة تقلّل ألم العميل.

سلاسل الاستعلام ترشّح المجموعات وتصفّها: GET /v1/articles?tag=api&page=2&limit=20 يجب أن توثّق القيم الافتراضية والحدود القصوى وترتيب الفرز. معاملات المسار تحدّد الموارد (/articles/what-is-an-api)؛ معاملات الاستعلام تُحكّم الطلب. خلطها بلا اتساق — أحياناً معرّف في الاستعلام فقط — يجبر كل عميل على استثناء واجهتك. وثّق أي المعاملات إلزامية، وأيها مستقر للتخزين المؤقت، وأيها يغيّر شكل الاستجابة.

طرق HTTP

«آمنة» تعني أن الخادم لا ينبغي أن يغيّر الحالة؛ idempotent تعني أن تكرار الطلب لا يضاعف الآثار الجانبية. التخزين المؤقت ومنطق إعادة المحاولة يعتمدان على هذه الدلالات.

الترويسات: بيانات وصفية يقرأها الخادم أولاً

• Content-Type يخبر الخادم كيف يحلّل الجسم (application/json).
• Accept يطلب JSON (application/json) أو تمثيلات أخرى.
• Authorization يحمل رموز bearer أو مفاتيح API أو اعتمادات خاصة بالمخطط.
• User-Agent وX-Request-ID وترويسات التتبع تساعد التسجيل والدعم.

الجسم وحِمَلات JSON

طلبات GET عادة بلا جسم؛ POST وPATCH غالباً ترسل مستندات JSON. الخوادم تتحقق من الحقول الإلزامية والأنواع وقواعد العمل قبل الكتابة في قاعدة البيانات. على العملاء إرسال JSON بترميز UTF-8 مع Content-Type صحيح، وتنسيق جميل للقراءة في التطوير فقط — المسافات البيضاء لا تغيّر المعنى لكنها تهدر بايتات. قبل لصق حمولة فاشلة في تذكرة، مرّرها بمنسّق: فاصلة ناقصة أو علامة اقتباس «ذكية» من جدول بيانات تبدو كخطأ خادم حتى يصبح JSON صالحاً.

استدعاء واحد: طلب واستجابة

HTTP نص أولاً على السلك: سطر طلب، ترويسات، سطر فارغ، ثم جسم اختياري؛ الخادم يجيب بسطر حالة، ترويسات، سطر فارغ، وجسم اختياري. واجهات JSON تبقي الطرفين قابلين للقراءة آلياً. الطلب أدناه ينشئ مقالاً؛ الاستجابة تعيد السجل المخزّن مع حقول يعيّنها الخادم.

POST /v1/articles HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOi…
Accept: application/json
Content-Length: 89

{
  "title": "What Is an API?",
  "slug": "what-is-an-api",
  "published": true
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /v1/articles/art_7k2m
Cache-Control: private, max-age=0

{
  "id": "art_7k2m",
  "slug": "what-is-an-api",
  "title": "What Is an API and How Does It Work?",
  "published": true,
  "created": "2026-10-04T14:22:00Z",
  "updated": "2026-10-04T14:22:00Z"
}

لاحظ كيف تعيد الاستجابة حقول العميل لكنها تضيف id وطوابع زمنية لم يرسلها العميل. GET لاحق /v1/articles/what-is-an-api قد يعيد 200 بنفس شكل JSON؛ PATCH قد يرسل فقط { "published": false } ويجيب 200 بالمستند المحدّث. json-formatter في SmartKitio يساعدك على مقارنة هذين الجسمين جنباً إلى جنب — أسماء الحقول والتداخل والفاصلة الزائدة تظهر فوراً حين يختلف بيئتان.

رموز الحالة تلخّص النتائج

رموز حالة HTTP ملخصات من ثلاث خانات: 2xx نجاح، 3xx إعادة توجيه، 4xx خطأ من العميل، 5xx فشل الخادم. الواجهات ما زالت تعيد أجسام أخطاء JSON برموز قابلة للقراءة آلياً، لكن الحالة تخبر الوسطاء والعملاء العامين كيف يعيدون المحاولة أو يخزّنون مؤقتاً. حين يعيد البوابة 502 Bad Gateway قد تكون المشكلة upstream؛ حين يعيد تطبيقك 422 فغالباً وصل JSON إلى المعالج لكنه فشل التحقق — http-status-lookup يوضّح الفئة بينما تقرأ الجسم.

معالجة الأخطاء على العميل

العملاء المتينون يعاملون الاستجابات غير 2xx كنتائج بحد ذاتها، لا استثناءات مدفونة في ضجيج وحدة التحكم. اقرأ الحالة، ثم حلّل JSON إن كان Content-Type هو application/json؛ بعض الوكلاء ما زالوا يعيدون صفحات HTML للخطأ عند 502، وهذا يرمي عند JSON.parse — هذا التمييز يوفر ساعات. الواجهات المستقرة توثّق غلاف خطأ: رمز نصي للفروع البرمجية، رسالة للبشر، ومصفوفات details اختيارية للتحقق.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": "validation_failed",
  "message": "Slug is already in use",
  "fields": {
    "slug": ["must be unique"]
  }
}

أنماط المصادقة

رموز bearer في ترويسة Authorization تهيمن على backends التطبيقات أحادية الصفحة والجوال. OAuth2 وOpenID Connect يفوّضان تسجيل الدخول لمزوّدي هوية. مفاتيح API في الترويسات بسيطة لكنها تتسرّب بسهولة من حزم العميل — فضّل رموزاً قصيرة العمر وتبادلاً من جانب الخادم. لا تضع أسراراً في سلاسل الاستعلام حيث تنسخها السجلات وترويسات Referer؛ إن اضطررت لوضع قيمة في URL فرمّزها بالنسبة المئوية واعتبرها عامة.

دورة حياة الطلب

حين يفشل استدعاء، ضيّق الطبقة قبل تعديل الشفرة: أخطاء مصافحة TLS لا تصل أبداً إلى محلّلات JSON؛ 401 يحدث في middleware قبل معالجك؛ 422 يعني أن المعالج نفّذ التحقق. سجّل الطلب الخام (الطريقة، URL، الترويسات، الجسم) وحالة الاستجابة في سطر log واحد أو تصدير HAR، ثم تحقق من JSON محلياً. هذا سير العمل هو سبب إقران json-formatter وhttp-status-lookup في الأدوات ذات الصلة لهذا المقال — هكذا يصحّح مكاملون الأنظمة فعلاً.

REST وأنماط أخرى (باختصار)

REST يستخدم دلالات HTTP وخوادم بلا حالة وعناوين URL موجهة للموارد — ما زال النموذج الذهني الافتراضي لواجهات HTTP العامة. GraphQL يرسل POST واحداً بمستند استعلام ليجلب العملاء رسوماً مُشكّلة في جولة واحدة. gRPC يستخدم Protocol Buffers على HTTP/2 لخدمات microservices داخلية بكفاءة. webhooks تعكس التدفق: الخادم يرسل POST إلى URL عند وقوع أحداث. اختر حسب العملاء والزمن والأدوات — لا حسب الموضة.

قراءة GET ناجح

GET /v1/articles/what-is-an-api HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGciOi…

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: private, max-age=60
ETag: "art_7k2m-v3"

{
  "id": "art_7k2m",
  "slug": "what-is-an-api",
  "title": "What Is an API and How Does It Work?",
  "updated": "2026-10-04"
}

الإصدارات والاستقرار

الواجهات العامة تعيش أطول من التطبيقات الفردية. الإصدارات تخبر العملاء أي عقد يتحدثون دون تجميد كل حقل إلى الأبد. النمط الأبرز بادئة مسار (/v1/، /v2/) حتى تتفرّع أشجار مسارات كاملة. الإصدارات بالترويسة (Accept: application/vnd.company.v2+json) تبقي عناوين URL مستقرة لكنها تتطلب عملاء منضبطين. معاملات الاستعلام (?api-version=2) تظهر في السجلات والتخزين المؤقت — استخدمها فقط إن قبلت ذلك الظهور.

• وثّق JSON خطأ مستقراً: code وmessage وتفاصيل على مستوى الحقل اختيارية.
• فضّل التغييرات الإضافية: حقول اختيارية جديدة ونقاط نهاية جديدة تكسر عملاء أقل من إعادة التسمية.
• أعلِن الإهمال بترويسات Sunset أو تواريخ قطع موثّقة؛ أبقِ v1 للقراءة فقط قبل الإزالة.
• ترويسات Idempotency-Key على POST تساعد إعادة المحاولة الآمنة للمدفوعات والإنشاء.
• انشر OpenAPI أو JSON Schema حتى تُفحص لصقات json-formatter مقابل الأشكال نفسها التي يتحقق منها خادمك.

حين ينكسر تكامل، قارن الطلب الفاشل بالعقد: الطريقة، المسار، Content-Type، ترويسة المصادقة، ومفاتيح JSON بالضبط. الصق أجسام الطلب والاستجابة في json-formatter لاكتشاف عدم تطابق camelCase أو سلسلة حيث يتوقع المخطط رقماً؛ أقرن ذلك بـ http-status-lookup حين لا يكفي الحالة وحده لمعرفة إن كان الإصلاح للعميل أو الخادم أو الوكيل بينهما.

ما يستحق التذكّر

• الواجهة هي العقد — عناوين URL والطرق والترويسات والأجسام والأخطاء — لا شعار إطار العمل على المستودع.
• اقرأ الحالة دائماً أولاً، ثم حلّل JSON؛ ليس كل جسم خطأ JSON.
• رمّز وفكّ ترميز URL عند حدود المكوّن؛ الأسرار في الترويسات، لا في سلاسل الاستعلام.
• أصدر إصدارات صراحة؛ التطور الإضافي يتفوق على كسر صامت.

json-formatter وhttp-status-lookup في SmartKitio مبنيان لحلقة التصحيح التي يصفها هذا المقال: تحقق من الحمولات ونسّقها محلياً، ثم ابحث عن رمز الحالة الذي استقبله عميلك أو curl. استخدمهما مع url-encoder حين تكون معاملات الاستعلام جزءاً من الطلب الفاشل.