نظرة عامة على تصميم واجهة برمجة التطبيقات

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

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

  • مستند OpenAPI
  • مخطط GraphQL

تقدّم الأقسام التالية مزيدًا من المعلومات حول مستندات OpenAPI وGraphQL والدور الذي تؤدّيه في دورة حياة واجهة برمجة التطبيقات. للاطّلاع على مقارنة بين خيارَي تصميم واجهة برمجة التطبيقات، يمكنك الرجوع إلى المقارنة بين REST وGraphQL في مشاركة المدونة هذه.

ما هي مواصفات OpenAPI؟


"تركّز مبادرة OpenAPI (OAI) على إنشاء وتطوير وترويج تنسيق وصف لواجهة برمجة التطبيقات محايد للبائعين استنادًا إلى مواصفات Swagger". لمزيد من المعلومات عن مبادرة OpenAPI، يُرجى الانتقال إلى https://openapis.org.

يستخدم مستند OpenAPI تنسيقًا عاديًا لوصف واجهة RESTful API. مكتوبًا بتنسيق JSON أو YAML، يمكن قراءة مستند OpenAPI آليًا، كما يسهل على المستخدمين قراءته وفهمه. تتيح مواصفات OpenAPI تقديم وصف رسمي لعناصر واجهة برمجة التطبيقات، مثل المسار الأساسي والمسارات والأفعال والعناوين ومعلَمات طلب البحث وأنواع المحتوى ونماذج الردود وغير ذلك. بالإضافة إلى ذلك، يتم استخدام مستند OpenAPI بشكل شائع لإنشاء مستندات واجهة برمجة التطبيقات.

في ما يلي جزء من مستند OpenAPI يصف نموذج "مرحبًا بالعالم" البسيط في Apigee. لمزيد من المعلومات، يُرجى الاطّلاع على مواصفات OpenAPI على GitHub.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

تتوفّر العديد من المصادر الممتازة للمعلومات حول مواصفات OpenAPI. يمكنك البدء بزيارة موقع مبادرة OpenAPI، حيث ستجد نظرات عامة ومدوّنات وروابط تؤدي إلى مواصفات OpenAPI. راجِع المواصفات للحصول على أوصاف تفصيلية لعناصر المخطط وأنواع البيانات.

تتوفّر مجموعة من الأمثلة على مستندات OpenAPI بتنسيقَي JSON وYAML يمكنك تنزيلها من مستودع مواصفات OpenAPI.

ما هو مخطط GraphQL؟

يصف مخطط GraphQL البيانات المتاحة في واجهة برمجة التطبيقات التي يمكن للعميل طلبها.

تشمل مزايا استخدام GraphQL ما يلي:

  • توفّر نقطة نهاية واحدة إمكانية الوصول إلى جميع الحقول لعملية معيّنة
  • تتيح لك لغة الاستعلام القوية، المعروفة باسم "لغة تعريف المخطط"، الوصول إلى البيانات التي تحتاج إليها بالضبط، ما يمنع استرداد بيانات أكثر أو أقل من المطلوب.
  • تتم معالجة طلبات البحث بشكل متوازٍ

لمزيد من المعلومات عن GraphQL، يُرجى الاطّلاع على graphql.org.

يوضّح المثال التالي مخطط GraphQL يحدّد نقطة إدخال البيانات (نوع الاستعلام) وعمليات الكتابة المتاحة (نوع التعديل) وأنواع البيانات.

type Query {
  Greeting: String
  students: [Student]
}
type Mutation {
  createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
  newStudent: Student!
}
type Student {
  Id: ID!
  firstName: String!
  lastName: String!
  password: String!
  collegeId: String!
}

يمكنك طلب البحث في مخطط GraphQL لعرض البيانات التي تحتاج إليها بالضبط كحمولة JSON.

طلب بحث GraphQL ونتائجه

ماذا يحدث إذا عدّلتُ مستندًا؟

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

عند تعديل مستند أو حذفه، سيؤثر ذلك في ما يلي:

  • في حال تعديل مستند، عليك تعديل العناصر ذات الصلة يدويًا، بما في ذلك خادم وكيل واجهة برمجة التطبيقات وأي منتجات واجهة برمجة تطبيقات تعرض مواردها، وإعادة إنشاء مستندات مرجعية لواجهة برمجة التطبيقات لعرض التغييرات التي تم إجراؤها في المستند.
  • في حال حذف مستند، عليك حذف العناصر ذات الصلة يدويًا، بما في ذلك خادم وكيل واجهة برمجة التطبيقات، وتعديل أي منتجات خاصة بواجهة برمجة التطبيقات لحذف الموارد ذات الصلة، وإعادة إنشاء مستند مرجعي لواجهة برمجة التطبيقات ليعكس عملية إزالة المستند وموارده.

ماذا يحدث عند إنشاء خادم وكيل لواجهة برمجة التطبيقات من مستند OpenAPI؟

في Edge، يمكنك إنشاء خوادم وكيلة لواجهة برمجة التطبيقات من مستندات OpenAPI. ببضع نقرات فقط، ستحصل على خادم وكيل لواجهة برمجة التطبيقات يتضمّن المسارات والمعلَمات والتدفّقات الشرطية ونقاط النهاية المستهدَفة التي يتم إنشاؤها تلقائيًا. بعد ذلك، يمكنك إضافة ميزات مثل أمان OAuth والحدّ من عدد الطلبات والتخزين المؤقت.

يمكنك إنشاء خادم وكيل لواجهة برمجة التطبيقات من مستند OpenAPI، كما هو موضّح في الأقسام التالية:

عند نشر واجهة برمجة التطبيقات، يمكنك أخذ لقطة من مستند OpenAPI لإنشاء مستندات مرجعية لواجهة برمجة التطبيقات. تمثّل هذه اللقطة نسخة معيّنة من مستند الوصف في متجر المواصفات.