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

أنت تعرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

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

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

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

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


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

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

إليك جزء من مستند OpenAPI يصف نموذج hello world البسيط من 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 لإنشاء مستندات مرجعية لواجهة برمجة التطبيقات. تمثل تلك اللقطة مراجعة معينة لمستند الوصف في مخزن المواصفات.