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

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. المعلومات

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

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

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

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


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

يستخدم مستند OpenAPI تنسيقًا عاديًا لوصف RESTful API. تتم كتابة مستند OpenAPI بتنسيق JSON أو YAML، وهو قابل للقراءة آليًا، ويسهل أيضًا على البشر قراءته وفهمه. تعمل مواصفات 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 Initiative من أفضل الأماكن التي يمكنك الاطّلاع فيها على ملخّصات ومدوّنات وروابط تؤدي إلى مواصفات 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 لإنشاء مستندات مرجعية لواجهة برمجة التطبيقات. تمثل تلك اللقطة نسخة سابقة محددة من مستند الوصف في مخزن المواصفات.