لماذا مثال متجر الحيوانات الأليفة Swagger تصميم واجهة برمجة تطبيقات REST سيئ؟

ملخص سريع

ينتهك Swagger Petstore مبادئ REST الأساسية: فهو يستخدم أسماء موارد مفردة بشكل غير متناسق، ويتضمن أفعال عمل في عناوين URL، ويعيد رموز حالة HTTP خاطئة، ويكشف كلمات المرور في طلبات GET، ويعيد مصفوفات مجردة بدون بيانات وصفية. يعمل Modern PetstoreAPI على إصلاح كل هذه المشكلات من خلال تصميم RESTful سليم، ومعالجة الأخطاء وفقًا لمعيار RFC 9457، وأنماط جاهزة للإنتاج.

مقدمة

لأكثر من عقد من الزمان، كان Swagger Petstore هو المثال الافتراضي لتعلم OpenAPI. لقد درسه ملايين المطورين، ونسخوا أنماطه، وبنوا واجهات برمجة تطبيقات إنتاجية بناءً على تصميمه. هناك مشكلة واحدة: إنه يعلمك بناء واجهات برمجة تطبيقات سيئة.

ينتهك Swagger Petstore مبادئ REST الأساسية، ويتضمن نقاط ضعف أمنية، ويعرض أنماطًا مضادة تضر بأنظمة الإنتاج. إنه مثل تعلم القيادة بسيارة تم تبديل دواستي الفرامل والوقود فيها—سوف تتعلم، ولكنك ستتعلم بشكل خاطئ.

الضرر حقيقي. المطورون الذين تعلموا من Swagger Petstore ينقلون هذه الأنماط المضادة إلى كود الإنتاج. يتم بناء واجهات برمجة التطبيقات بأسماء غير متناسقة، وطرق HTTP خاطئة، وثغرات أمنية. تفوت مراجعات الكود هذه المشكلات لأن "هذه هي طريقة Petstore".

💡

إذا كنت تقوم ببناء أو اختبار واجهات برمجة تطبيقات REST، فإن Apidog يساعدك على التحقق من تصميم API مقابل مبادئ REST، واختبار سلوك نقطة النهاية، واكتشاف عيوب التصميم قبل وصولها إلى الإنتاج. يمكنك استيراد مواصفات OpenAPI، وتشغيل اختبارات آلية، والتأكد من أن API الخاص بك يتبع اتفاقيات REST الصحيحة.

تنزيل التطبيق

في هذا الدليل، ستتعرف بالضبط على الأخطاء في Swagger Petstore، ولماذا هذه المشكلات مهمة، وكيف يصلحها Modern PetstoreAPI بأنماط جاهزة للإنتاج. سترى مقارنات جنبًا إلى جنب، وتفهم تأثير كل انتهاك، وتكتشف كيفية اختبار واجهات برمجة تطبيقاتك بشكل صحيح باستخدام Apidog.

مشكلة إرث Swagger Petstore

تم إنشاء Swagger Petstore في عام 2011 كمثال بسيط لمواصفات Swagger (الآن OpenAPI). وقد خدم غرضه: إظهار كيفية كتابة مواصفات OpenAPI. لكنه لم يكن يهدف أبدًا إلى أن يكون مرجعًا لتصميم واجهات برمجة تطبيقات REST.

لماذا أصبح المعيار الفعلي

عندما يتعلم المطورون OpenAPI، يبدأون بالمثال الرسمي. Swagger Petstore هو هذا المثال. إنه موجود في الوثائق والبرامج التعليمية ومولدات الكود. إذا كنت قد استخدمت Swagger UI أو Swagger Codegen، فقد رأيته.

المشكلة: يفترض المطورون أن "المثال الرسمي = أفضل ممارسة". ينسخون الأنماط دون التشكيك فيها. تستخدم دورات تصميم API ذلك كأداة تعليمية. تبني الشركات واجهات برمجة تطبيقات داخلية باتباع هيكلها.

تكلفة الأمثلة السيئة

الأمثلة السيئة تتراكم بمرور الوقت:

المطورون المبتدئون يتعلمون أنماطًا مضادة - لا يعرفون أن هذه أخطاء
مولدات الكود تديم المشكلات - ترث حزم SDK المولدة العيوب
أدوات التوثيق تعرض أمثلة سيئة - يعرض Swagger UI Petstore بشكل افتراضي
الشركات تبني واجهات برمجة تطبيقات إنتاجية بهذه الطريقة - "إذا كان جيدًا بما فيه الكفاية لـ Swagger..."

ربما أثر Swagger Petstore على عدد أكبر من تصاميم واجهات برمجة التطبيقات أكثر من أي مثال آخر في التاريخ. ولهذا السبب فإن عيوبه مهمة.

انتهاكات REST الحرجة في Swagger Petstore

دعنا نفحص انتهاكات REST المحددة في Swagger Petstore ولماذا هي خاطئة.

1. تسمية الموارد غير المتناسقة (المفرد مقابل الجمع)

الانتهاك:

GET /pet/{petId}           ← مفرد
GET /store/inventory       ← جمع
POST /pet                  ← مفرد
GET /user/{username}       ← مفرد

لماذا هو خطأ:

تمثل موارد REST مجموعات. والمجموعة تكون بصيغة الجمع. عندما تصل إلى /pets، فإنك تصل إلى مجموعة الحيوانات الأليفة. عندما تصل إلى /pets/123، فإنك تصل إلى العنصر 123 في مجموعة الحيوانات الأليفة.

خلط المفرد والجمع يكسر هذا النموذج الذهني. هل /pet/123 يصل إلى مجموعة الحيوانات الأليفة أم إلى مورد حيوان أليف واحد؟ عدم الاتساق يخلق ارتباكًا.

إصلاح Modern PetstoreAPI:

GET /pets/{petId}          ← دائمًا بصيغة الجمع
GET /stores/inventory      ← متناسق
POST /pets                 ← جمع للمجموعة
GET /users/{username}      ← جمع في كل مكان

يستخدم Modern PetstoreAPI أسماء موارد بصيغة الجمع بشكل متناسق عبر جميع نقاط النهاية. تحقق من وثائق REST API لهيكل نقطة النهاية الكاملة.

2. أفعال العمل في عناوين URL

الانتهاك:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2
GET /user/login?username=john&password=secret
GET /user/logout

لماذا هو خطأ:

يجب أن تمثل عناوين URL لـ REST الموارد (الأسماء)، وليس الإجراءات (الأفعال). طريقة HTTP هي الفعل. تعني GET /pets "احصل على مورد الحيوانات الأليفة". إضافة findByStatus زائدة عن الحاجة—هذا ما تستخدم من أجله معلمات الاستعلام.

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

إصلاح Modern PetstoreAPI:

GET /pets?status=AVAILABLE              ← المورد + الفلتر
GET /pets?tags=tag1,tag2                ← معلمات الاستعلام للفلترة
POST /auth/login                        ← مورد مصادقة منفصل
POST /auth/logout                       ← نقاط نهاية مصادقة RESTful

يستخدم Modern PetstoreAPI معلمات الاستعلام للفلترة وموارد مصادقة منفصلة. راجع دليل المصادقة لأنماط المصادقة الصحيحة.

3. رموز حالة HTTP الخاطئة

الانتهاك:

POST /pet
Response: 200 OK          ← يجب أن يكون 201 Created

DELETE /pet/{petId}
Response: 200 OK          ← يجب أن يكون 204 No Content
{
  "message": "Pet deleted"
}

لماذا هو خطأ:

رموز حالة HTTP لها معانٍ محددة:

200 OK يعني "نجح الطلب، هذا هو المورد"
201 Created يعني "تم إنشاء المورد، إليك مكان العثور عليه"
204 No Content يعني "نجح الطلب، لا يوجد محتوى لإرجاعه"

استخدام 200 لكل شيء يكسر دلالات HTTP. لا يمكن للعملاء التمييز بين "تم استرداد المورد" و "تم إنشاء المورد". إرجاع نص مع DELETE يهدر النطاق الترددي—لا يحتاج العميل إلى نص تأكيد.

إصلاح Modern PetstoreAPI:

POST /pets
Response: 201 Created
Location: /pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "status": "AVAILABLE"
}

DELETE /pets/{petId}
Response: 204 No Content
(لا يوجد نص)

يستخدم Modern PetstoreAPI رموز حالة HTTP الصحيحة ويتضمن رؤوس Location للموارد التي تم إنشاؤها. تحقق من دليل رموز حالة HTTP للتعيين الكامل.

4. المصفوفات المجردة بدون بيانات وصفية

الانتهاك:

GET /pet/findByStatus?status=available
Response: 200 OK
[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

لماذا هو خطأ:

إرجاع المصفوفات المجردة يخلق مشاكل:

لا توجد بيانات وصفية للترقيم - كم عدد العناصر الإجمالية؟ في أي صفحة أنا؟
لا توجد قابلية للتوسع - لا يمكن إضافة بيانات وصفية دون كسر العملاء
لا توجد روابط HATEOAS - لا يمكن تضمين روابط التنقل
خطر اختطاف JSON - المصفوفات المجردة عرضة لهجمات معينة

إصلاح Modern PetstoreAPI:

GET /pets?status=AVAILABLE
Response: 200 OK
{
  "data": [
    {"id": "019b4132-70aa-764f-b315-e2803d882a24", "name": "Fluffy"},
    {"id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6", "name": "Buddy"}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 45,
    "totalPages": 3
  },
  "links": {
    "self": "/pets?status=AVAILABLE&page=1",
    "next": "/pets?status=AVAILABLE&page=2",
    "last": "/pets?status=AVAILABLE&page=3"
  }
}

يغلف Modern PetstoreAPI جميع المجموعات في كائنات تحتوي على بيانات وصفية وروابط HATEOAS. راجع دليل الترقيم للحصول على تفاصيل التنفيذ.

5. معايير الأخطاء المفقودة

الانتهاك:

Response: 400 Bad Request
{
  "code": 400,
  "message": "Invalid input"
}

لماذا هو خطأ:

تنسيق الخطأ هذا غير قياسي ويوفر الحد الأدنى من المعلومات:

لا يوجد معرف لنوع الخطأ
لا توجد أخطاء تحقق على مستوى الحقل
لا توجد رموز خطأ قابلة للقراءة آليًا
لا يتبع RFC 9457 (تفاصيل المشكلة)

إصلاح Modern PetstoreAPI:

Response: 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "status",
      "message": "Status must be one of: AVAILABLE, PENDING, SOLD",
      "code": "INVALID_ENUM"
    }
  ]
}

يستخدم Modern PetstoreAPI تفاصيل مشكلة RFC 9457 لجميع الأخطاء. راجع دليل معالجة الأخطاء لتنسيق الخطأ الكامل.

كوارث أمنية في التصميم القديم

بصرف النظر عن انتهاكات REST، يحتوي Swagger Petstore على مشكلات أمنية خطيرة.

طلب GET مع كلمات المرور

الانتهاك:

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

لماذا هي كارثة:

تظهر كلمات المرور في طلبات GET في:

سجل المتصفح - أي شخص لديه حق الوصول إلى المتصفح يرى كلمة المرور
سجلات الخادم - تسجل خوادم الويب عناوين URL الكاملة بما في ذلك معلمات الاستعلام
رؤوس الإحالة (Referrer headers) - إذا نقر المستخدم على رابط بعد تسجيل الدخول، فإن الموقع التالي يرى كلمة المرور
سجلات الوكيل (Proxy logs) - تسجل وكلاء الشركات جميع عناوين URL
إشارات المتصفح المرجعية - قد يقوم المستخدمون بوضع إشارة مرجعية لعنوان URL الخاص بتسجيل الدخول

هذه ثغرة أمنية حرجة. لا ينبغي أبدًا أن تكون كلمات المرور في عناوين URL.

إصلاح Modern PetstoreAPI:

POST /auth/login
Content-Type: application/json
{
  "username": "john",
  "password": "secret123"
}

Response: 200 OK
{
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "expiresIn": 3600
}

يستخدم Modern PetstoreAPI طريقة POST للمصادقة مع هيئات JSON. لا تظهر كلمات المرور أبدًا في عناوين URL. راجع دليل المصادقة لأنماط OAuth 2.0 و JWT.

مفاتيح API في معلمات الاستعلام

الانتهاك:

GET /pet/123?api_key=abc123secret

لماذا هو خطأ:

تحتوي مفاتيح API في معلمات الاستعلام على نفس المشكلات التي تواجهها كلمات المرور في عناوين URL:

يتم تسجيلها في كل مكان
مرئية في سجل المتصفح
تُرسل في رؤوس الإحالة
يتم تخزينها مؤقتًا بواسطة الوكلاء

إصلاح Modern PetstoreAPI:

GET /pets/019b4132-70aa-764f-b315-e2803d882a24
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

يستخدم Modern PetstoreAPI رؤوس Authorization القياسية لمفاتيح وتوكنات API. راجع دليل الأمان لأنماط المصادقة.

كيف يحل Modern PetstoreAPI هذه المشكلات

تم بناء Modern PetstoreAPI من الصفر لإظهار تصميم API لـ REST الصحيح. إليك ما يجعله مختلفًا:

تصميم REST جاهز للإنتاج

أسماء موارد جمع متناسقة - /pets، /orders، /users
عناوين URL موجهة نحو الموارد - لا توجد أفعال عمل، فقط أسماء
رموز حالة HTTP الصحيحة - 201 للإنشاء، 204 للحذف، رموز أخطاء صحيحة
أغلفة المجموعات - جميع القوائم تتضمن ترقيم الصفحات والبيانات الوصفية
أخطاء RFC 9457 - تنسيق خطأ قياسي مع التحقق على مستوى الحقل

المعايير الحديثة

OpenAPI 3.2 - أحدث المواصفات مع جميع الميزات
RFC 9457 - تفاصيل المشكلة لواجهات برمجة تطبيقات HTTP
تحديد معدل IETF - رؤوس RateLimit-* القياسية
ISO 8601 - تنسيقات صحيحة للتاريخ/الوقت
UUIDv7 - معرفات فريدة قابلة للفرز

دعم بروتوكولات متعددة

على عكس Swagger Petstore (REST فقط)، يدعم Modern PetstoreAPI:

REST (OpenAPI 3.2)
GraphQL
gRPC
WebSocket
Server-Sent Events (SSE)
MQTT
Webhooks
Model Context Protocol (MCP)

راجع دليل البروتوكولات للحصول على تفاصيل التنفيذ.

منطق عمل حقيقي

يتضمن Modern PetstoreAPI ميزات واقعية:

معالجة الدفع
إدارة المخزون
تنفيذ الطلبات
إشعارات الويب هوك (Webhook)
توصيات الحيوانات الأليفة المدعومة بالذكاء الاصطناعي
تحميل ومعالجة الصور

تحقق من وثائق API للحصول على مجموعة الميزات الكاملة.

اختبار تصميم API لـ REST باستخدام Apidog

يساعدك Apidog على التحقق من تصميم API لـ REST واكتشاف الانتهاكات قبل وصولها إلى الإنتاج.

استيراد والتحقق من مواصفات OpenAPI

# استيراد مواصفات Modern PetstoreAPI
1. افتح Apidog
2. انقر على "استيراد" ← "OpenAPI"
3. أدخل: https://petstoreapi.com/openapi.json
4. يتحقق Apidog من المواصفات وينشئ حالات اختبار

يكتشف Apidog تلقائيًا:

تسمية الموارد غير المتناسقة
رموز حالة HTTP المفقودة
هياكل الاستجابة غير الصالحة
مشكلات الأمان في المصادقة

اختبار مبادئ REST

أنشئ حالات اختبار تتحقق من الامتثال لـ REST:

الاختبار: أسماء الموارد بصيغة الجمع

// سكريبت اختبار Apidog
pm.test("Endpoint uses plural resource name", function() {
  const url = pm.request.url.toString();
  pm.expect(url).to.match(/\/pets\/|\/orders\/|\/users\//);
  pm.expect(url).to.not.match(/\/pet\/|\/order\/|\/user\//);
});

الاختبار: رموز الحالة الصحيحة

pm.test("POST returns 201 Created", function() {
  if (pm.request.method === "POST") {
    pm.response.to.have.status(201);
    pm.response.to.have.header("Location");
  }
});

pm.test("DELETE returns 204 No Content", function() {
  if (pm.request.method === "DELETE") {
    pm.response.to.have.status(204);
    pm.expect(pm.response.text()).to.be.empty;
  }
});

الاختبار: المجموعات تحتوي على بيانات وصفية

pm.test("Collection response includes pagination", function() {
  const response = pm.response.json();
  pm.expect(response).to.have.property("data");
  pm.expect(response).to.have.property("pagination");
  pm.expect(response.pagination).to.have.property("page");
  pm.expect(response.pagination).to.have.property("totalItems");
});

مقارنة Petstore القديم بالجديد

استورد كلتا المواصفات إلى Apidog وقم بإجراء مقارنات جنبًا إلى جنب:

استيراد Swagger Petstore: https://petstore.swagger.io/v2/swagger.json
استيراد Modern PetstoreAPI: https://petstoreapi.com/openapi.json
تشغيل اختبارات آلية على كليهما
مقارنة النتائج لمعرفة الاختلافات

سيسلط Apidog الضوء على انتهاكات التصميم في Swagger Petstore ويوضح كيف يصلحها Modern PetstoreAPI.

دليل الترحيل: من تصميم Petstore القديم إلى التصميم الحديث

إذا قمت ببناء API استنادًا إلى Swagger Petstore، فإليك كيفية الترحيل إلى تصميم REST الصحيح:

الخطوة 1: إصلاح أسماء الموارد

قبل:

GET /pet/{petId}
POST /pet
DELETE /pet/{petId}

بعد:

GET /pets/{petId}
POST /pets
DELETE /pets/{petId}

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

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

الخطوة 2: إزالة أفعال العمل

قبل:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2

بعد:

GET /pets?status=AVAILABLE
GET /pets?tags=tag1,tag2

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

إعادة توجيه نقاط النهاية القديمة إلى الجديدة باستخدام 301 Moved Permanently
تحديث حزم SDK للعميل لاستخدام نقاط النهاية الجديدة
إضافة تحقق من معلمات الاستعلام

الخطوة 3: إصلاح رموز حالة HTTP

قبل:

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK with body

بعد:

POST /pets → 201 Created with Location header
DELETE /pets/{petId} → 204 No Content (no body)

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

هذا تغيير جذري للعملاء الذين يتحققون من رموز الحالة
إصدار API الخاص بك (الإصدار 2) برموز حالة صحيحة
توثيق التغييرات بوضوح
توفير جدول زمني للترحيل

الخطوة 4: تغليف المجموعات

قبل:

[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

بعد:

{
  "data": [...],
  "pagination": {...},
  "links": {...}
}

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

هذا تغيير جذري
إنشاء نقاط نهاية للإصدار 2 باستجابات مغلفة
إلغاء نقاط نهاية الإصدار 1
تحديث كود العميل للتعامل مع الهيكل الجديد

الخطوة 5: تطبيق أخطاء RFC 9457

قبل:

{
  "code": 400,
  "message": "Invalid input"
}

بعد:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [...]
}

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

إضافة رأس Content-Type: application/problem+json
تضمين كلا تنسيقات الأخطاء القديمة والجديدة خلال الفترة الانتقالية
تحديث معالجة أخطاء العميل
إزالة التنسيق القديم بعد فترة الترحيل

التأثير الواقعي لتصميم API السيئ

لتصميم API السيئ تكاليف حقيقية:

ارتباك المطورين

عندما تنتهك واجهات برمجة التطبيقات مبادئ REST، يضيع المطورون الوقت في:

تخمين طريقة HTTP التي يجب استخدامها
اكتشاف أنماط التسمية غير المتناسقة
تصحيح رموز الحالة غير المتوقعة
معالجة الأخطاء بدون هيكل مناسب

التكلفة: ساعات من وقت المطور لكل دمج

أخطاء العميل

تؤدي واجهات برمجة التطبيقات غير المتناسقة إلى أخطاء من جانب العميل:

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

التكلفة: حوادث الإنتاج وتأثير على العملاء

نقاط الضعف الأمنية

عيوب التصميم تخلق مخاطر أمنية:

تسجيل كلمات المرور في عناوين URL
تخزين مفاتيح API مؤقتًا في معلمات الاستعلام
نقص المصادقة على نقاط النهاية الحساسة
رسائل الأخطاء غير الصحيحة تسرب معلومات النظام

التكلفة: اختراقات البيانات وانتهاكات الامتثال

الديون التقنية

الأمثلة السيئة تتفاقم مع مرور الوقت:

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

التكلفة: عبء صيانة طويل الأمد

الخلاصة

لقد أدى Swagger Petstore الغرض منه كمثال بسيط لـ OpenAPI، ولكن حان الوقت للمضي قدمًا. لقد أثرت انتهاكاته لـ REST، ومشكلاته الأمنية، وأنماطه المضادة على عدد كبير جدًا من واجهات برمجة تطبيقات الإنتاج.

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

اختبر واجهات برمجة تطبيقاتك باستخدام Apidog لاكتشاف انتهاكات التصميم مبكرًا. استورد مواصفات OpenAPI الخاصة بك، وقم بتشغيل اختبارات آلية، وتأكد من أن واجهات برمجة تطبيقاتك تتبع مبادئ REST قبل وصولها إلى الإنتاج.

الخطوات التالية:

استكشف وثائق Modern PetstoreAPI
قارن تصميم API الخاص بك بأنماط Modern PetstoreAPI
استورد مواصفات OpenAPI الخاصة بك إلى Apidog للتحقق من الصحة
أصلح انتهاكات REST باستخدام دليل الترحيل أعلاه
اعتمد RFC 9457 لمعالجة الأخطاء

لقد ولى عصر أمثلة API السيئة. ابنِ واجهات برمجة التطبيقات بالطريقة الصحيحة باستخدام Modern PetstoreAPI.

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

لماذا أنشأ Swagger مثالاً سيئاً؟

تم إنشاء Swagger Petstore في عام 2011 كمثال بسيط لتوضيح مواصفات Swagger. لم يكن الغرض منه أن يكون مرجعًا لتصميم واجهات برمجة تطبيقات REST. المشكلة هي أنه أصبح المثال المعياري الفعلي، وتم نسخ عيوبه بواسطة ملايين المطورين.

هل يجب أن أتوقف عن استخدام Swagger Petstore؟

نعم، لتعلم تصميم API لـ REST. استخدم Modern PetstoreAPI بدلاً من ذلك. فهو يوضح مبادئ REST الصحيحة، والمعايير الحديثة، والأنماط الجاهزة للإنتاج. يعلم Petstore القديم أنماطًا مضادة تضر بأنظمة الإنتاج.

هل Modern PetstoreAPI جاهز للإنتاج؟

نعم. يتضمن Modern PetstoreAPI منطق عمل واقعي، ومعالجة أخطاء صحيحة، ومصادقة، وتحديد معدل الاستخدام، وميزات أمان. يمكنك نشره بحد أدنى من التعديلات أو استخدامه كمرجع لتصميم API الخاص بك.

كيف أختبر ما إذا كان API الخاص بي يتبع مبادئ REST؟

استورد مواصفات OpenAPI الخاصة بك إلى Apidog وقم بتشغيل اختبارات آلية. يتحقق Apidog من تسمية الموارد، ورموز حالة HTTP، وهياكل الاستجابة، وأنماط الأمان. يمكنك أيضًا مقارنة API الخاص بك جنبًا إلى جنب مع Modern PetstoreAPI.

ما هو أكبر خطأ في Swagger Petstore؟

استخدام GET /user/login مع كلمات المرور في معلمات الاستعلام. هذا يكشف كلمات المرور في سجل المتصفح، وسجلات الخادم، ورؤوس الإحالة—وهي ثغرة أمنية حرجة. استخدم دائمًا POST مع هيئات JSON للمصادقة.

هل يمكنني الترحيل من أنماط Swagger Petstore تدريجياً؟

نعم. ادعم كلاً من نقاط النهاية القديمة والجديدة خلال فترة انتقالية. أضف تحذيرات بالإهمال إلى نقاط النهاية القديمة، وحدث الوثائق، وراقب الاستخدام. أزل نقاط النهاية القديمة بعد أن يهاجر العملاء (عادةً بعد 6-12 شهرًا).

هل يدعم Modern PetstoreAPI GraphQL و gRPC؟

نعم. على عكس Swagger Petstore (REST فقط)، يدعم Modern PetstoreAPI بروتوكولات متعددة: REST، و GraphQL، و gRPC، و WebSocket، و SSE، و MQTT، و Webhooks، و MCP. راجع دليل البروتوكولات للحصول على التفاصيل.

كيف أقنع فريقي بإصلاح تصميم API الخاص بنا؟

أظهر لهم التكاليف الحقيقية: ارتباك المطورين، وأخطاء العملاء، ونقاط الضعف الأمنية، والديون التقنية. استخدم Apidog لإظهار الانتهاكات في API الحالي الخاص بك. قارن تصميمك بـ Modern PetstoreAPI واعرض التحسينات.