لماذا يجب ألا تستخدم الأفعال في عناوين URL الخاصة بواجهات برمجة تطبيقات REST؟

ملخص

يجب أن تحتوي عناوين URL الخاصة بواجهات برمجة تطبيقات REST على أسماء (موارد)، وليس أفعالاً (إجراءات). تعد طرق HTTP (GET، POST، PUT، DELETE) هي الأفعال. استخدام أفعال الإجراءات مثل /getUser أو /createOrder ينتهك مبادئ REST، ويخلق عدم اتساق، ويجعل صيانة واجهات برمجة التطبيقات أكثر صعوبة. تستخدم Modern PetstoreAPI عناوين URL موجهة نحو الموارد في جميع أنحاء واجهتها.

مقدمة

أنت تصمم نقطة نهاية لواجهة برمجة تطبيقات للبحث عن الحيوانات الأليفة حسب الحالة. قد تكون غريزتك الأولى هي: GET /findPetsByStatus?status=available. إنها وصفية وواضحة وتخبرك بالضبط بما تفعله. لكنها خاطئة أيضاً.

يجب أن تستخدم واجهات برمجة تطبيقات REST الأسماء في عناوين URL، وليس الأفعال. طريقة HTTP هي الفعل. GET /pets?status=available هو التصميم الصحيح. يمثل عنوان URL المورد (الحيوانات الأليفة)، وتمثل الطريقة الإجراء (الحصول).

ارتكب Swagger Petstore القديم هذا الخطأ بنقاط نهاية مثل /pet/findByStatus و /pet/findByTags. تنتهك أفعال الإجراءات هذه في عناوين URL مبادئ REST وتخلق مشاكل في الصيانة. تعالج Modern PetstoreAPI هذا باستخدام عناوين URL الموجهة نحو الموارد بشكل متسق.

في هذا الدليل، ستتعرف على سبب عدم وجود الأفعال في عناوين URL الخاصة بواجهات برمجة تطبيقات REST، وكيفية تصميم نقاط نهاية موجهة نحو الموارد، وكيفية تطبيق Modern PetstoreAPI لذلك بشكل صحيح.

مشكلة الأفعال في واجهات برمجة تطبيقات REST

تشير أفعال الإجراءات في عناوين URL إلى أنك تفكر بمصطلحات RPC (الاستدعاء عن بُعد للإجراءات)، وليس بمصطلحات REST.

عناوين URL بأسلوب RPC (خطأ)

POST /createUser
GET /getUser?id=123
PUT /updateUser
DELETE /deleteUser?id=123
GET /findUsersByRole?role=admin
POST /sendEmail
GET /calculateTotal

تصف عناوين URL هذه الإجراءات. وهي تُقرأ مثل استدعاءات الدوال: createUser()، getUser()، sendEmail().

عناوين URL بأسلوب REST (صحيح)

POST /users
GET /users/123
PUT /users/123
DELETE /users/123
GET /users?role=admin
POST /emails
GET /orders/123/total

تصف عناوين URL هذه الموارد. وتوفر طريقة HTTP الإجراء.

لماذا هذا مهم

الاتساق: تتبع عناوين URL الخاصة بواجهات REST نمطًا يمكن التنبؤ به. بمجرد معرفة اسم المورد، تعرف جميع نقاط النهاية:

• GET /pets - سرد الحيوانات الأليفة
• POST /pets - إنشاء حيوان أليف
• GET /pets/{id} - الحصول على حيوان أليف
• PUT /pets/{id} - تحديث حيوان أليف
• DELETE /pets/{id} - حذف حيوان أليف

باستخدام عناوين URL المستندة إلى الأفعال، تكون كل نقطة نهاية فريدة. لا يوجد نمط يمكن اتباعه.

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

• /findPetsByStatus
• /findPetsByTags
• /findPetsByOwner
• /findPetsByBreed
• /searchPets
• /queryPets

تستخدم عناوين URL الموجهة نحو الموارد معلمات الاستعلام:

• GET /pets?status=available
• GET /pets?tags=friendly
• GET /pets?owner=john
• GET /pets?breed=labrador

نقطة نهاية واحدة تتعامل مع جميع عمليات التصفية.

لماذا تعد طرق HTTP هي الأفعال

تستفيد REST من الأفعال المضمنة في HTTP. لست بحاجة إلى اختراع أفعالك الخاصة.

طرق HTTP تتوافق مع عمليات CRUD

POST   → إنشاء
GET    → قراءة
PUT    → تحديث (استبدال)
PATCH  → تحديث (جزئي)
DELETE → حذف

لهذه الطرق دلالات محددة. GET آمن ومتكرر (idempotent). POST ينشئ موارد. DELETE يزيلها.

مثال: إدارة المستخدمين

خطأ (أفعال في عناوين URL):

POST /createUser
GET /getUser?id=123
POST /updateUser
POST /deleteUser

تستخدم كل عملية عنوان URL مختلفًا. لا تنقل طريقة HTTP معنى.

صحيح (طرق HTTP كأفعال):

POST /users           ← إنشاء مستخدم
GET /users/123        ← الحصول على مستخدم
PUT /users/123        ← تحديث مستخدم
DELETE /users/123     ← حذف مستخدم

يبقى عنوان URL كما هو. تتغير الطريقة.

فوائد استخدام طرق HTTP

1. التخزين المؤقت (Caching): يمكن تخزين طلبات GET مؤقتًا. تعرف المتصفحات والبروكسيات ذلك. إذا استخدمت POST /getUser، فسيتعطل التخزين المؤقت.

2. التكرارية (Idempotency): طرق PUT و DELETE متكررة. استدعاؤها عدة مرات له نفس تأثير استدعائها مرة واحدة. هذا مهم لمنطق إعادة المحاولة.

3. الأمان: GET آمن — لا يغير الحالة. يمكن للأدوات وبرامج الزحف استدعاء نقاط نهاية GET بأمان.

4. التوافق مع المعايير: عملاء HTTP، والبروكسيات، وذاكرات التخزين المؤقت تفهم طرق HTTP. إنها لا تفهم أفعالك المخصصة.

أمثلة حقيقية من Swagger Petstore

يتضمن Swagger Petstore القديم عدة نقاط نهاية قائمة على الأفعال.

المثال 1: البحث عن الحيوانات الأليفة حسب الحالة

Swagger Petstore (خطأ):

GET /pet/findByStatus?status=available

المشاكل:

• findByStatus هي عبارة فعلية
• غير متسق مع نقطة النهاية /pet/{id}
• لا يمكن تمديده بسهولة (ماذا عن البحث بمعايير أخرى؟)

Modern PetstoreAPI (صحيح):

GET /pets?status=AVAILABLE

الفوائد:

• موجه نحو الموارد (/pets)
• يستخدم معلمات الاستعلام للتصفية
• متسق مع نقاط النهاية الأخرى
• سهل التمديد: GET /pets?status=AVAILABLE&species=dog

راجع وثائق Modern PetstoreAPI REST للاطلاع على التنفيذ الكامل.

المثال 2: البحث عن الحيوانات الأليفة حسب العلامات

Swagger Petstore (خطأ):

GET /pet/findByTags?tags=tag1,tag2

Modern PetstoreAPI (صحيح):

GET /pets?tags=friendly,trained

المثال 3: تسجيل دخول المستخدم

Swagger Petstore (خطأ):

GET /user/login?username=john&password=secret

مشاكل متعددة:

• login هو فعل
• استخدام GET للمصادقة (كارثة أمنية)
• كلمات المرور في معلمات استعلام URL

Modern PetstoreAPI (صحيح):

POST /auth/login
Content-Type: application/json

{
  "username": "john",
  "password": "secret123"
}

الفوائد:

• موجه نحو الموارد (/auth)
• طريقة HTTP الصحيحة (POST)
• بيانات الاعتماد في جسم الطلب، وليس عنوان URL
• يعيد رمز JWT للطلبات اللاحقة

كيف تعالج Modern PetstoreAPI هذا

Modern PetstoreAPI تستخدم عناوين URL الموجهة نحو الموارد في جميع أنحاء واجهتها.

إدارة الحيوانات الأليفة

GET /pets                    ← سرد جميع الحيوانات الأليفة
GET /pets?status=AVAILABLE   ← التصفية حسب الحالة
GET /pets?species=dog        ← التصفية حسب النوع
GET /pets/{id}               ← الحصول على حيوان أليف محدد
POST /pets                   ← إنشاء حيوان أليف جديد
PUT /pets/{id}               ← تحديث حيوان أليف
PATCH /pets/{id}             ← تحديث جزئي
DELETE /pets/{id}            ← حذف حيوان أليف

لا أفعال. فقط موارد وطرق HTTP.

إدارة الطلبات

GET /orders                  ← سرد الطلبات
GET /orders/{id}             ← الحصول على طلب
POST /orders                 ← إنشاء طلب
PUT /orders/{id}             ← تحديث طلب
DELETE /orders/{id}          ← إلغاء طلب
GET /orders/{id}/items       ← الحصول على عناصر الطلب

العمليات المعقدة

للعمليات التي لا تتوافق بشكل واضح مع CRUD، تستخدم Modern PetstoreAPI موارد فرعية:

POST /orders/{id}/payment    ← معالجة الدفع للطلب
POST /orders/{id}/shipment   ← إنشاء شحنة للطلب
POST /pets/{id}/adoption     ← بدء عملية التبني

لا تزال هذه موجهة نحو الموارد. /orders/{id}/payment يمثل مورد الدفع لطلب.

عندما تبدو الأفعال ضرورية

بعض العمليات لا تتناسب مع نموذج CRUD. إليك كيفية التعامل معها بدون أفعال في عناوين URL.

عمليات البحث

خطأ:

GET /searchPets?query=labrador

الخيار الصحيح 1 (معلمات الاستعلام):

GET /pets?search=labrador

الخيار الصحيح 2 (مورد البحث):

GET /pets/search?q=labrador

الخيار الصحيح 3 (طريقة QUERY):

QUERY /pets
Content-Type: application/json

{
  "query": "labrador",
  "filters": {
    "status": "AVAILABLE"
  }
}

تدعم Modern PetstoreAPI جميع الأنماط الثلاثة حسب التعقيد.

الحسابات

خطأ:

GET /calculateShipping?weight=10&destination=NY

صحيح:

GET /shipping-estimates?weight=10&destination=NY

المورد هو "تقديرات الشحن"، وليس إجراء الحساب.

العمليات المجمعة

خطأ:

POST /batchDeletePets

صحيح:

DELETE /pets?ids=1,2,3

أو استخدم مورد دفعات:

POST /pets/batch-operations
Content-Type: application/json

{
  "operation": "delete",
  "ids": [1, 2, 3]
}

الإجراءات التي تغير الحالة

خطأ:

POST /activateUser
POST /deactivateUser

صحيح:

PATCH /users/{id}
Content-Type: application/json

{
  "status": "ACTIVE"
}

تغييرات الحالة هي تحديثات للمورد.

اختبار تصميم URL باستخدام Apidog

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

استيراد Modern PetstoreAPI

1. استورد مواصفات Modern PetstoreAPI OpenAPI
2. يقوم Apidog تلقائيًا بإنشاء حالات اختبار
3. راجع هيكل نقطة النهاية والتسمية

التحقق من وجود أفعال في عناوين URL

أنشئ قاعدة تحقق مخصصة في Apidog:

// التحقق مما إذا كان URL يحتوي على أفعال إجراءات شائعة
const verbs = ['get', 'create', 'update', 'delete', 'find', 'search',
               'calculate', 'process', 'send', 'fetch'];
const url = request.url.toLowerCase();

for (const verb of verbs) {
  if (url.includes(`/${verb}`)) {
    throw new Error(`URL يحتوي على فعل: ${verb}. استخدم عناوين URL الموجهة نحو الموارد بدلاً من ذلك.`);
  }
}

اختبار اتساق نقطة النهاية

يمكن لـ Apidog التحقق من أن نقاط النهاية ذات الصلة تتبع أنماطًا متسقة:

✓ GET /pets
✓ POST /pets
✓ GET /pets/{id}
✓ PUT /pets/{id}
✓ DELETE /pets/{id}

تستخدم جميعها نفس المورد الأساسي (/pets).

المقارنة بـ Modern PetstoreAPI

استخدم Modern PetstoreAPI كمرجع:

1. استورد واجهة برمجة التطبيقات الخاصة بك و Modern PetstoreAPI إلى Apidog
2. قارن هياكل نقاط النهاية جنبًا إلى جنب
3. حدد أوجه عدم الاتساق واستخدام الأفعال
4. أعد هيكلة واجهة برمجة التطبيقات الخاصة بك لتتوافق مع مبادئ REST

استراتيجيات الترحيل

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

الاستراتيجية 1: الترقيم بالإصدارات

أنشئ إصدارًا جديدًا من واجهة برمجة التطبيقات بعناوين URL صحيحة:

# واجهة برمجة التطبيقات القديمة (الإصدار 1)
GET /api/v1/findPetsByStatus?status=available

# واجهة برمجة التطبيقات الجديدة (الإصدار 2)
GET /api/v2/pets?status=available

حافظ على الإصدار 1 للتوافق مع الإصدارات السابقة، وشجع على الترحيل إلى الإصدار 2.

الاستراتيجية 2: استخدام الأسماء المستعارة

ادعم كلا من عناوين URL القديمة والجديدة مؤقتًا:

# عنوان URL قديم (مهمل)
GET /pet/findByStatus?status=available

# عنوان URL جديد (مفضل)
GET /pets?status=available

أعد تحذيرات الإهمال في الردود:

{
  "data": [...],
  "warnings": [
    {
      "code": "نقطة_نهاية_مهملة",
      "message": "نقطة النهاية هذه مهملة. استخدم GET /pets?status=available بدلاً من ذلك.",
      "sunset": "2027-01-01"
    }
  ]
}

الاستراتيجية 3: إعادة التوجيهات

استخدم عمليات إعادة توجيه HTTP 301 للترحيلات البسيطة:

GET /pet/findByStatus?status=available
→ 301 تم النقل بشكل دائم
Location: /pets?status=available

يعمل هذا لطلبات GET ولكن ليس لـ POST أو PUT أو DELETE.

الخلاصة

يجب أن تحتوي عناوين URL الخاصة بواجهات برمجة تطبيقات REST على أسماء (موارد)، وليس أفعالاً (إجراءات). توفر طرق HTTP الأفعال. يخلق هذا المبدأ واجهات برمجة تطبيقات متسقة وقابلة للتوسع وسهلة الصيانة.

انتهك Swagger Petstore القديم هذا الأمر بنقاط نهاية مثل /pet/findByStatus. تعالج Modern PetstoreAPI هذا باستخدام عناوين URL الموجهة نحو الموارد في جميع أنحاء واجهتها: /pets?status=AVAILABLE.

النقاط الرئيسية:

• استخدم الأسماء في عناوين URL: /pets، /orders، /users
• دع طرق HTTP تكون هي الأفعال: GET، POST، PUT، DELETE
• استخدم معلمات الاستعلام للتصفية: /pets?status=available
• للعمليات المعقدة، استخدم الموارد الفرعية: /orders/{id}/payment
• اختبر تصميم واجهة برمجة التطبيقات الخاصة بك باستخدام Apidog لاكتشاف استخدام الأفعال مبكرًا

راجع وثائق Modern PetstoreAPI للاطلاع على أمثلة كاملة لتصميم عناوين URL الموجهة نحو الموارد.

الأسئلة الشائعة

هل يمكنني استخدام الأفعال في عناوين URL الخاصة بواجهات REST؟

نادرًا. إذا كانت عملية ما لا تتناسب حقًا مع نموذج المورد (مثل /search أو /login)، فقد يكون الفعل مقبولًا. ولكن في 95% من الحالات، يمكنك نمذجتها كمورد.

ماذا عن /login و /logout؟

هذه استثناءات شائعة. تستخدم العديد من واجهات برمجة التطبيقات /auth/login و /auth/logout. بدلاً من ذلك، نمذجها كموارد: POST /sessions (تسجيل الدخول) و DELETE /sessions/{id} (تسجيل الخروج).

كيف أتعامل مع الاستعلامات المعقدة؟

استخدم معلمات الاستعلام للتصفية البسيطة: /pets?status=available&species=dog. للاستعلامات المعقدة، استخدم طريقة HTTP QUERY أو مورد بحث: POST /pets/search.

ماذا لو كانت عمليتي لا تتوافق مع CRUD؟

نمذجها كمورد فرعي. بدلاً من POST /processPayment، استخدم POST /orders/{id}/payment. الدفع هو مورد متعلق بالطلب.

كيف أختبر ما إذا كانت عناوين URL الخاصة بي موجهة نحو الموارد؟

استخدم Apidog لاستيراد مواصفات OpenAPI الخاصة بك والتحقق من وجود أفعال في عناوين URL. قارن بنية واجهة برمجة التطبيقات الخاصة بك بـ Modern PetstoreAPI كمرجع.

هل يجب أن أستخدم /pets/search أم /pets?search=query؟

كلاهما مقبول. /pets?search=query أبسط للبحث الأساسي. /pets/search أو QUERY /pets يعمل بشكل أفضل للبحث المعقد بمعلمات متعددة.

كيف أقوم بالترحيل من عناوين URL المستندة إلى الأفعال؟

استخدم ترقيم إصدارات واجهة برمجة التطبيقات (/v2/pets بدلاً من /v1/findPets)، وأضف تحذيرات إهمال، وامنح العملاء وقتًا للترحيل. راجع قسم استراتيجيات الترحيل للحصول على التفاصيل.

هل تستخدم Modern PetstoreAPI أي أفعال في عناوين URL؟

تتجنب Modern PetstoreAPI استخدام الأفعال في عناوين URL. يتم نمذجة عمليات مثل البحث والتصفية والمصادقة كموارد أو تستخدم معلمات الاستعلام. راجع وثائق واجهة برمجة تطبيقات REST للحصول على أمثلة.