تصميم API: "بروتوكول الحوار" بين الواجهة الأمامية والخلفية

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

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

0. سؤال أولاً: هل مررت بأي من هذه الكوابيس؟

المشهد الأول: تسمية الواجهات بشكل عشوائي

GET /getUserData
GET /fetchUserInfo
GET /queryUserById
GET /users/query

أربع واجهات، نفس الوظيفة، لكن أنماط التسمية مختلفة تماماً. الموظف الجديد يحتار: أي واحدة يجب أن أستخدم؟

المشهد الثاني: معالجة الأخطاء بطرق متضاربة

json

// البعض يعيد رمز حالة HTTP
HTTP/1.1 404 Not Found

// البعض يعيد 200 + code
HTTP/1.1 200 OK
{ "code": 404, "message": "المستخدم غير موجود" }

// البعض يرمي استثناءً مباشرة
HTTP/1.1 200 OK
{ "error": "حدث خطأ" }

الواجهة الأمامية لا تعرف كيف تحكم على نجاح الطلب.

المشهد الثالث: بنية الاستجابة مختلفة لكل واجهة

json

// الواجهة A
{ "data": { ... } }

// الواجهة B
{ "result": { ... } }

// الواجهة C
{ "content": { ... } }

تنسيق الإرجاع لكل واجهة مختلف، مما يضطر الواجهة الأمامية للمعالجة بشكل منفصل لكل واجهة.

تصميم API الجيد يشبه نظام الطلبات في المطعم — قائمة واضحة، إجراءات منظمة، وتنبيهات عند الأخطاء.

1. ما هو API؟

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

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

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

1.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. فلسفة تصميم API: RPC / REST / GraphQL / gRPC

قبل البدء في تصميم RESTful التفصيلي، دعنا نتعرف على أربعة أنماط رئيسية لتصميم API:

REST

Most common

Representational State Transfer was introduced by Roy Fielding in 2000. It models the system as resources identified by URLs and operated on with HTTP methods.

Example: fetch user information

GET    /users           # Fetch user list
GET    /users/123       # Fetch one user
POST   /users           # Create user
PUT    /users/123       # Full update
PATCH  /users/123       # Partial update
DELETE /users/123       # Delete user

Key features

✓URLs are nouns, not verbs

✓HTTP methods express actions

✓Stateless requests carry all needed context

✓Cacheable and friendly to layered systems

Use casesPublic APIs, CRUD operations, and domains with clear resource boundaries

Official sitehttps://restfulapi.net/

📊 Style quick comparison

Feature

RPC

REST

GraphQL

gRPC

Core idea

Procedure-oriented

Resource-oriented

Data-oriented

Method-oriented

URL style

Verb-first

Noun-first

Single endpoint

URL-independent

Learning curve

Low

Medium

High

Performance

Average

Good

Excellent

Usage share

~30%

~50%

~15%

~5%

2.1 REST مقابل RESTful: ما الفرق؟

كثير من الناس يخلطون بين هذين المفهومين:

المفهوم	المعنى	الوصف
REST	نمط معماري	فلسفة تصميم اقترحها Roy Fielding، تحتوي على مجموعة من القيود
RESTful	مطابق لنمط REST	صفة، تعني أن تصميم API يتبع مبادئ REST

تشبيه:

REST مثل "البساطة" — فلسفة تصميم
RESTful API مثل "غرفة بأسلوب بسيط" — تطبيق ملموس لهذه الفلسفة

قيود REST الستة:

القيد	الوصف
فصل العميل عن الخادم	تطوير مستقل للواجهة الأمامية والخلفية، فصل الواجهات
عديم الحالة	كل طلب يحتوي على جميع المعلومات اللازمة، الخادم لا يحفظ حالة الجلسة
قابل للتخزين المؤقت	يجب أن توضح الاستجابة ما إذا كانت قابلة للتخزين المؤقت، لتحسين الأداء
واجهة موحدة	استخدام طرق HTTP وأكواد الحالة القياسية
نظام متعدد الطبقات	العميل لا يحتاج لمعرفة أي طبقة من الخادم يتصل بها
الكود عند الطلب (اختياري)	يمكن للخادم توسيع وظائف العميل

💡 لماذا REST هو الأكثر استخداماً؟

تكلفة تعلم منخفضة: بروتوكول HTTP نفسه يجسد فكرة REST
نظام بيئي ناضج: أدوات، أطر عمل، ووثائق غنية
قابلية عامة عالية: يمكن استدعاؤه من أي لغة وأي منصة
سهل التخزين المؤقت: طلبات GET قابلة للتخزين المؤقت بطبيعتها، صديقة لـ CDN

3. تصميم RESTful: اجعل عنوان URL يتحدث

REST (Representational State Transfer) هو نمط معماري، فكرته الأساسية هي:

تجريد الأشياء على الشبكة إلى "موارد" (Resource)
استخدام URL لتعريف الموارد
استخدام طرق HTTP للتعامل مع الموارد

3.1 تشبيه بالمستودع

مفهوم المستودع	مقابل REST	مثال
عنوان الرف	URL	`/users`، `/orders`
طريقة التشغيل	طرق HTTP	GET (عرض)، POST (إدخال)
البضائع	الموارد	بيانات المستخدم، بيانات الطلب

المبدأ الأساسي: URL هو اسم، وليس فعل.

3.2 قواعد تصميم URL

القاعدة	مثال خاطئ	مثال صحيح	الوصف
استخدم الأسماء لا الأفعال	`/getUsers`	`/users`	URL يمثل المورد، وطريقة HTTP تمثل العملية
استخدم صيغة الجمع	`/user`	`/users`	توحيد أسلوب الجمع
أحرف صغيرة + شرطة	`/UserProfiles`	`/user-profiles`	URL حساس لحالة الأحرف
تجنب التداخل العميق	`/a/b/c/d/e`	`/a/b/c`	الحد الأقصى 3 مستويات
التصفية بمعاملات الاستعلام	`/products/phone/5000`	`/products?cat=phone`	شروط التصفية بمعامل `?`

💡 حساسية حالة الأحرف في URL

توحيد استخدام الأحرف الصغيرة + الشرطة (-) هو الأسلوب الأكثر أماناً، لتجنب فوضى حالة الأحرف وعدم تناسق أسلوب الشرطة السفلية.

3.3 اختيار طرق HTTP

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

💡 ما هو Idempotency؟

Idempotency: تنفيذ العملية عدة مرات يعطي نفس النتيجة.

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

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

4. أكواد الحالة: اجعل الخطأ "يتحدث"

أكواد حالة HTTP هي الطريقة القياسية التي يخبر بها الخادم العميل "ماذا حدث".

4.1 تصنيف أكواد الحالة

التصنيف	المعنى	أكواد الحالة النموذجية
2xx	نجاح	200 OK، 201 Created، 204 No Content
3xx	إعادة توجيه	301 نقل دائم، 304 غير معدل
4xx	خطأ من العميل	400 خطأ في المعاملات، 401 غير مصرح، 404 غير موجود
5xx	خطأ من الخادم	500 خطأ داخلي، 503 الخدمة غير متاحة

4.2 عرض أكواد الحالة الشائعة

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

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. معالجة الأخطاء: "الرفض" بأناقة

معالجة الأخطاء الجيدة تمكن العميل من "معرفة ما حدث من خلال رمز الحالة"، بدلاً من التخمين.

4.1 "دليل تجنب الفخاخ" في معالجة الأخطاء

الفخ 1: إرجاع 200 لجميع الأخطاء

json

// ❌ ممارسة خاطئة
HTTP/1.1 200 OK
{ "error": "حدث خطأ" }

المشكلة: طبقة التخزين المؤقت ستخزن هذه الاستجابة "الناجحة"، ولن يتمكن نظام المراقبة من اكتشاف المشكلة.

الفخ 2: رسائل خطأ عامة جداً

json

// ❌ ممارسة خاطئة
HTTP/1.1 400 Bad Request
{ "message": "خطأ في المعاملات" }

المشكلة: العميل لا يعرف أي معامل خاطئ، ولماذا هو خاطئ.

الفخ 3: كشف معلومات حساسة

json

// ❌ ممارسة خطيرة
HTTP/1.1 500 Internal Server Error
{ "stack": "at UserService.login...", "sql": "SELECT * FROM..." }

خطر: يكشف بنية الكود واستعلامات قاعدة البيانات، ويمكن للمهاجمين استخدام هذه المعلومات.

5.2 عرض معالجة الأخطاء الصحيحة

👇 جرب بنفسك: قارن بين تصميم استجابة الخطأ "الجيد" و"السيء":

Error Handling Demo

// Compare poor and good error handling

> ▋

Response structure

Click a button above to view an error response example

💡 Click a button to compare poor and good error response design.

6. التحكم في الإصدارات: "التوافق مع الإصدارات السابقة" لـ API

6.1 لماذا نحتاج التحكم في الإصدارات؟

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

إذا لم تقم بالتحكم في الإصدارات:

التطبيق الجديد يستدعي الواجهة الجديدة → طبيعي
التطبيق القديم يستدعي الواجهة الجديدة → حقول مفقودة، ينهار!

الممارسة الصحيحة:

/v1/orders - الواجهة القديمة، تستمر في خدمة التطبيق القديم
/v2/orders - الواجهة الجديدة، الوظائف الجديدة هنا

6.2 استراتيجيات التحكم في الإصدارات

الاستراتيجية	مثال	المزايا	العيوب
مسار URL	`/v1/users`	بديهي، سهل التخزين المؤقت	URL يصبح أطول
رأس الطلب	`Accept: vnd.api.v2+json`	URL نظيف	غير مناسب للتصحيح
معاملات الاستعلام	`/users?version=2`	بسيط	غير قياسي بما فيه الكفاية

6.3 مثال على تطور الإصدارات

بواجهة المستخدم كمثال، عرض التطور من v1 إلى v2:

الواجهة	v1 (القديم)	v2 (الجديد)	وصف التغيير
جلب المستخدم	`GET /v1/users` يرجع: `name, email`	`GET /v2/users` يرجع: `name, email, avatar, phone`	إضافة حقول الصورة ورقم الهاتف
إنشاء طلب	`POST /v1/orders` يستقبل: `items[]`	`POST /v2/orders` يستقبل: `items[], coupons[]`	إضافة دعم القسائم
عمليات مجمعة	لا يوجد	`POST /v2/orders/batch`	إضافة واجهة إنشاء مجمع

💡 أفضل ممارسات التحكم في الإصدارات

الحفاظ على التوافق مع الإصدارات السابقة: صيانة واجهة v1 لمدة 6-12 شهراً على الأقل، لإعطاء وقت للعملاء للترقية
تحديث الوثائق بشكل متزامن: كل إصدار له وثائق API مستقلة
إعلان الإيقاف: إخطار مسبق بموعد إيقاف v1، وتوجيه المستخدمين للترحيل
مراقبة الاستخدام: إحصاء عدد استدعاءات v1، والتأكد من إمكانية الإيقاف الآمن قبل إيقاف الخدمة

7. تصميم بنية الاستجابة

بنية الاستجابة هي "عقد البيانات" للتعاون بين الواجهة الأمامية والخلفية، التنسيق الموحد يقلل بشكل كبير من تكلفة التواصل.

Why use a unified response format?

❌ Problem: endpoints return inconsistent shapes

// Endpoint A
{ "data": { "user": {...} } }

// Endpoint B
{ "result": { "user": {...} } }

// Endpoint C
{ "user": {...} }

The frontend must handle every endpoint separately, which creates duplicate and fragile code.

✅ Solution: unified response format

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "request_id": "req-xxx"
}

💡Use request_id for troubleshooting. UUID v4 or Snowflake IDs are common choices.

7.1 مراجع من ممارسات الشركات الكبرى

دليل تصميم Google API

راجع Google API Design Guide، تطلب Google أن تحتوي جميع استجابات أخطاء API على بنية رسالة google.rpc.Status:

json

{
  "error": {
    "code": 429,
    "message": "الموارد غير كافية، يرجى المحاولة لاحقاً",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_AVAILABILITY",
        "domain": "compute.googleapis.com",
        "metadata": {
          "zone": "us-east1-a",
          "service": "compute"
        }
      }
    ]
  }
}

المتطلبات الأساسية:

يجب أن تتضمن ErrorInfo لتوفير معرف خطأ قابل للقراءة آلياً
message موجه للمطورين، يصف المشكلة والحل بلغة موجزة
مصفوفة details يمكن أن تتضمن LocalizedMessage (رسائل مترجمة)، Help (روابط مساعدة) إلخ

دليل Microsoft REST API

راجع Microsoft REST API Guidelines، تؤكد Microsoft على اتساق الاستجابة:

تصنيف الأخطاء والأعطال:

الخطأ (Error): ينتج عن إرسال العميل بيانات غير صالحة، يرجع 4xx، لا يؤثر على توفر API
العطل (Fault): عدم قدرة الخادم على الاستجابة بشكل صحيح لطلب صالح، يرجع 5xx، يؤثر على توفر API

مواصفات رؤوس الاستجابة:

Date: يجب إرجاعه، باستخدام تنسيق RFC 5322 (توقيت GMT)
Content-Type: يجب إرجاعه
ETag: يجب إرجاعه للموارد التي تدعم التحكم التفاؤلي بالتزامن

دليل تطوير Alibaba Java

راجع Alibaba Java Development Manual، لدى Alibaba المواصفات التالية لاستجابة API:

كائن الإرجاع الموحد:

java

public class Result<T> {
    private Integer code;
    private String message;
    private T data;
    private String requestId;
}

تصميم مقسم لأكواد الخطأ:

النطاق	النوع	مثال
0	نجاح	0
1xxxx	خطأ في المعاملات	10001 معامل إلزامي مفقود
2xxxx	خطأ في العمل	20001 رصيد غير كاف
3xxxx	خطأ في المصادقة	30001 غير مسجل الدخول
5xxxx	خطأ في النظام	50001 خطأ في قاعدة البيانات

تصميم استجابة Stripe API

راجع Stripe API Documentation، تصميم استجابة الخطأ في Stripe دقيق للغاية:

json

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "param": "number",
    "decline_code": "insufficient_funds",
    "doc_url": "https://stripe.com/docs/error-codes/card-declined"
  }
}

نقاط التميز في التصميم:

type يميز نوع الخطأ: api_error، card_error، invalid_request_error
param يشير إلى المعامل المحدد الخاطئ، مما يمكن الواجهة الأمامية من تحديد حقل النموذج مباشرة
doc_url يوفر رابط التوثيق، ليتمكن المطورون من التعمق في الفهم
decline_code يوفر سبب خطأ أكثر تفصيلاً

مواصفات JSON:API

راجع JSON:API Specification، هذه مواصفة استجابة JSON API معتمدة على نطاق واسع في الصناعة:

json

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "شرح مفصل لمواصفات JSON:API"
    },
    "relationships": {
      "author": {
        "data": { "type": "users", "id": "9" }
      }
    }
  },
  "included": [
    {
      "type": "users",
      "id": "9",
      "attributes": {
        "name": "تشانغ سان"
      }
    }
  ]
}

التصميم الأساسي:

data يحتوي على المورد الرئيسي، يجب أن يتضمن type و id
attributes تخزن خصائص المورد
relationships تصف ارتباطات الموارد
included يتجنب الطلبات المكررة، ويعيد البيانات المرتبطة دفعة واحدة

تصميم استجابة GitHub REST API

راجع GitHub REST API Documentation، تصميم استجابة GitHub يركز على تجربة المطور:

استجابة النجاح:

json

{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "owner": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://github.com/images/error/octocat_happy.gif"
  },
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World"
}

استجابة الخطأ:

json

{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest"
}

نقاط التميز في التصميم:

الاستجابة تتضمن تنسيقات URL متعددة (html_url، url) لتسهيل الاستخدام في سيناريوهات مختلفة
استجابة الخطأ تتضمن documentation_url يشير إلى التوثيق
استخدام رأس الاستجابة Link لتنفيذ التنقل بين الصفحات

تصميم استجابة Twitter/X API v2

راجع Twitter API v2 Documentation، Twitter API v2 يستخدم تنسيق استجابة بسيط:

json

{
  "data": {
    "id": "1460323737035677698",
    "text": "Hello, Twitter!"
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
      }
    ]
  }
}

نقاط التميز في التصميم:

data يحتوي على البيانات الرئيسية، includes يحتوي على البيانات المرتبطة (مشابه لـ JSON:API)
يدعم اختيار الحقول: ?tweet.fields=created_at,public_metrics
التقسيم لصفحات يستخدم next_token و previous_token

7.2 ملخص أفضل الممارسات

بناءً على المواصفات المذكورة أعلاه، يجب أن يتبع تصميم بنية الاستجابة المبادئ التالية:

الأولوية للاتساق: جميع الواجهات تستخدم نفس بنية الاستجابة، مما يمكن الواجهة الأمامية من تغليف طبقة الطلبات بشكل موحد
قابل للقراءة آلياً: كود الخطأ + سبب الخطأ (reason) يمكّن البرنامج من المعالجة التلقائية
مناسب للبشر: وصف message واضح، يتضمن اقتراحات للحل
قابل للتتبع: request_id يمر عبر سلسلة الطلب بأكملها، مما يسهل تحديد المشكلات
دعم التدويل: توسيع الرسائل المترجمة من خلال details

7.3 مواصفات تصميم حقل data

data هو نواة الاستجابة، وتصميمه يؤثر مباشرة على كفاءة تطوير الواجهة الأمامية.

Single object vs list

Single object

{
  "code": 0,
  "data": {
    "id": 123,
    "name": "Alice"
  }
}

List

{
  "code": 0,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "total": 100
    }
  }
}

List data should be wrapped in items, with pagination metadata in pagination.

💡Follow ISO 8601 for time values and keep JSON field names in snake_case.

7.4 تصميم متقدم لاستجابة الخطأ

Validation errors

{
  "code": 10001,
  "message": "Validation failed",
  "data": {
    "errors": [
      {
        "field": "email",
        "message": "Invalid email format",
        "value": "invalid-email"
      },
      {
        "field": "password",
        "message": "Password must be at least 8 characters",
        "value": "123"
      }
    ]
  }
}

fieldField name, so the frontend can locate the form input

messageUser-friendly error description

valueSubmitted value from the client, optional

💡Error messages should be machine-readable and human-friendly so the frontend can handle them consistently.

روابط مرجعية

8. تطبيق عملي: مثال على تصميم API لنظام التجارة الإلكترونية

# وحدة المستخدمين
GET    /v1/users                    # جلب قائمة المستخدمين
POST   /v1/users                    # إنشاء مستخدم جديد
GET    /v1/users/{id}               # جلب تفاصيل المستخدم
PUT    /v1/users/{id}               # تحديث كامل للمستخدم
PATCH  /v1/users/{id}               # تحديث جزئي للمستخدم
DELETE /v1/users/{id}               # حذف المستخدم

# وحدة الطلبات
GET    /v1/users/{id}/orders        # جلب طلبات مستخدم معين
POST   /v1/orders                   # إنشاء طلب
GET    /v1/orders/{id}              # جلب تفاصيل الطلب
PATCH  /v1/orders/{id}/status       # تحديث حالة الطلب

# وحدة المنتجات (تصفية معقدة بمعاملات الاستعلام)
GET    /v1/products?category=phone&price_max=5000&sort=price_desc&page=1

9. استخدام الذكاء الاصطناعي للمساعدة في تصميم API

يمكن للذكاء الاصطناعي مساعدتك في إنشاء تصميم API متوافق مع المواصفات بسرعة. المفتاح هو تقديم سياق واضح وشروط مقيدة.

9.1 قالب التلميح

أنت مهندس خلفي كبير، خبير في تصميم RESTful API. الرجاء مساعدتي في تصميم مجموعة من واجهات API.

## خلفية العمل
[صف سيناريو عملك، مثلاً: نظام التجارة الإلكترونية، منصة المدونات، إدارة المهام إلخ]

## المتطلبات الوظيفية
[اذكر وحدات الوظائف المطلوبة، مثلاً:
- إدارة المستخدمين: التسجيل، تسجيل الدخول، المعلومات الشخصية
- إدارة الطلبات: إنشاء طلب، استعلام الطلبات، إلغاء الطلب
- إدارة المنتجات: قائمة المنتجات، تفاصيل المنتج، البحث]

## متطلبات التصميم
1. اتباع مواصفات RESTful
2. URL يستخدم أسماء الجمع، أحرف صغيرة + شرطة
3. استخدام صحيح لطرق HTTP (GET/POST/PUT/PATCH/DELETE)
4. تنسيق استجابة موحد: { code, message, data, request_id }
5. استخدام معقول لأكواد الحالة
6. التحكم في الإصدارات: طريقة مسار URL (/v1/)

## تنسيق الإخراج
الرجاء الإخراج بالتنسيق التالي:

### قائمة الواجهات
| الطريقة | URL | الوصف | جسم الطلب | جسم الاستجابة |
|------|-----|------|--------|--------|

### مثال الطلب/الاستجابة
[أمثلة مفصلة للواجهات الرئيسية]

### شرح أكواد الحالة
[أكواد الحالة المستخدمة ومعانيها]

9.2 مثال تطبيقي: API طلبات التجارة الإلكترونية

إدخال التلميح:

أنت مهندس خلفي كبير، خبير في تصميم RESTful API. الرجاء مساعدتي في تصميم مجموعة من واجهات API لنظام طلبات التجارة الإلكترونية.

## خلفية العمل
منصة تجارة إلكترونية B2C، يمكن للمستخدمين تصفح المنتجات، تقديم الطلبات، وعرض حالة الطلبات.

## المتطلبات الوظيفية
- وحدة الطلبات: إنشاء طلب، استعلام قائمة الطلبات، استعلام تفاصيل الطلب، إلغاء الطلب، دفع الطلب
- وحدة سلة التسوق: إضافة منتج، تعديل الكمية، حذف منتج، عرض سلة التسوق

## متطلبات التصميم
1. اتباع مواصفات RESTful
2. URL يستخدم أسماء الجمع، أحرف صغيرة + شرطة
3. استخدام صحيح لطرق HTTP
4. تنسيق استجابة موحد
5. التحكم في الإصدارات: /v1/

مثال إخراج AI:

الطريقة	URL	الوصف
`POST`	`/v1/orders`	إنشاء طلب
`GET`	`/v1/orders`	استعلام قائمة الطلبات
`GET`	`/v1/orders/{id}`	استعلام تفاصيل الطلب
`PATCH`	`/v1/orders/{id}/status`	تحديث حالة الطلب (إلغاء/دفع)
`GET`	`/v1/users/{id}/cart`	جلب سلة التسوق
`POST`	`/v1/users/{id}/cart/items`	إضافة منتج إلى سلة التسوق
`PATCH`	`/v1/users/{id}/cart/items/{itemId}`	تعديل كمية منتج في سلة التسوق
`DELETE`	`/v1/users/{id}/cart/items/{itemId}`	حذف منتج من سلة التسوق

9.3 ملاحظات التصميم بمساعدة AI

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

💡 تقنيات المتابعة

"الرجاء إضافة أمثلة استجابة الخطأ لكل واجهة"
"الرجاء النظر في معاملات التقسيم لصفحات، الترتيب، والتصفية"
"الرجاء إضافة شرح التحكم في الصلاحيات للواجهات"
"الرجاء التحقق من التوافق مع أفضل ممارسات RESTful"

جدول المصطلحات السريع

المصطلح	الإنجليزية	الشرح
API	Application Programming Interface	اتفاق الحوار بين البرامج
REST	Representational State Transfer	نمط معماري، يستخدم URL لتعريف الموارد
المورد	Resource	المفهوم الأساسي في معمارية REST، له معرف فريد (URL)
Idempotency	Idempotency	تنفيذ العملية عدة مرات يعطي نفس النتيجة
رمز الحالة	Status Code	حالة الاستجابة المعرفة في بروتوكول HTTP
التحكم في الإصدارات	Versioning	جعل API القديم والجديد يتعايشان، للترقية السلسة
جسم الطلب	Request Body	البيانات المرسلة مع طلبات POST/PUT/PATCH
جسم الاستجابة	Response Body	البيانات التي يعيدها الخادم
Header	Header	البيانات الوصفية للطلب/الاستجابة (مثل Content-Type)
المصادقة	Authentication	التحقق من "من أنت" (تسجيل الدخول، Token)
الترخيص	Authorization	التحقق من "ما يمكنك فعله" (الصلاحيات)

تصميم API: "بروتوكول الحوار" بين الواجهة الأمامية والخلفية ​

0. سؤال أولاً: هل مررت بأي من هذه الكوابيس؟ ​

1. ما هو API؟ ​

1.1 تشبيه بالمطعم ​

1.2 طلب API كامل ​

2. فلسفة تصميم API: RPC / REST / GraphQL / gRPC ​

REST

2.1 REST مقابل RESTful: ما الفرق؟ ​

3. تصميم RESTful: اجعل عنوان URL يتحدث ​

3.1 تشبيه بالمستودع ​

3.2 قواعد تصميم URL ​

3.3 اختيار طرق HTTP ​

4. أكواد الحالة: اجعل الخطأ "يتحدث" ​

4.1 تصنيف أكواد الحالة ​

4.2 عرض أكواد الحالة الشائعة ​

5. معالجة الأخطاء: "الرفض" بأناقة ​

4.1 "دليل تجنب الفخاخ" في معالجة الأخطاء ​

5.2 عرض معالجة الأخطاء الصحيحة ​

6. التحكم في الإصدارات: "التوافق مع الإصدارات السابقة" لـ API ​

6.1 لماذا نحتاج التحكم في الإصدارات؟ ​

6.2 استراتيجيات التحكم في الإصدارات ​

6.3 مثال على تطور الإصدارات ​

7. تصميم بنية الاستجابة ​

Why use a unified response format?

7.1 مراجع من ممارسات الشركات الكبرى ​

7.2 ملخص أفضل الممارسات ​

7.3 مواصفات تصميم حقل data ​

Single object vs list

7.4 تصميم متقدم لاستجابة الخطأ ​

Validation errors

8. تطبيق عملي: مثال على تصميم API لنظام التجارة الإلكترونية ​

9. استخدام الذكاء الاصطناعي للمساعدة في تصميم API ​

9.1 قالب التلميح ​

9.2 مثال تطبيقي: API طلبات التجارة الإلكترونية ​

9.3 ملاحظات التصميم بمساعدة AI ​

جدول المصطلحات السريع ​

تصميم API: "بروتوكول الحوار" بين الواجهة الأمامية والخلفية

0. سؤال أولاً: هل مررت بأي من هذه الكوابيس؟

1. ما هو API؟

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

1.2 طلب API كامل

2. فلسفة تصميم API: RPC / REST / GraphQL / gRPC

2.1 REST مقابل RESTful: ما الفرق؟

3. تصميم RESTful: اجعل عنوان URL يتحدث

3.1 تشبيه بالمستودع

3.2 قواعد تصميم URL

3.3 اختيار طرق HTTP

4. أكواد الحالة: اجعل الخطأ "يتحدث"

4.1 تصنيف أكواد الحالة

4.2 عرض أكواد الحالة الشائعة

5. معالجة الأخطاء: "الرفض" بأناقة

4.1 "دليل تجنب الفخاخ" في معالجة الأخطاء

5.2 عرض معالجة الأخطاء الصحيحة

6. التحكم في الإصدارات: "التوافق مع الإصدارات السابقة" لـ API

6.1 لماذا نحتاج التحكم في الإصدارات؟

6.2 استراتيجيات التحكم في الإصدارات

6.3 مثال على تطور الإصدارات

7. تصميم بنية الاستجابة

7.1 مراجع من ممارسات الشركات الكبرى

7.2 ملخص أفضل الممارسات

7.3 مواصفات تصميم حقل data

7.4 تصميم متقدم لاستجابة الخطأ

8. تطبيق عملي: مثال على تصميم API لنظام التجارة الإلكترونية

9. استخدام الذكاء الاصطناعي للمساعدة في تصميم API

9.1 قالب التلميح

9.2 مثال تطبيقي: API طلبات التجارة الإلكترونية

9.3 ملاحظات التصميم بمساعدة AI

جدول المصطلحات السريع