ما هو OpenAPI؟

يُتيح ملف OpenAPI ، المعروف أيضًا باسم مستند OpenAPI أو مواصفات OpenAPI، للمطورين وصف واجهة برمجة التطبيقات. تصف هذه المواصفات أيضًا كيفية استخدام واجهة برمجة التطبيقات (API)، بما في ذلك نقاط النهاية المتاحة، ومعلمات العمليات، وطرق المصادقة، ومعلومات أخرى. هذه المواصفات مكتوبة إما بلغة YAML أو JSON، ويُستخدم مخطط JSON لوصف تنسيقات البيانات داخل واجهة برمجة التطبيقات (API).

تُعد OpenAPI بمثابة وثيقة وعقد في آنٍ واحد (معنويًّا، حيث تصف ما يجب أن يفعله واجهة برمجة التطبيقات — وهي ليست ملزمة قانونًا) بين مستهلكي ومُنتجي واجهة برمجة التطبيقات (API). فهي بمثابة "مصدر واحد للحقيقة" توفّر التعليمات بتنسيق موحّد.

يعمل هذا التوحيد على تبسيط تكامل واستهلاك واجهة برمجة التطبيقات (API). إنها تُمكِّن البشر والحواسيب على حدٍّ سواء من فهم وظيفة وبنية واجهة برمجة تطبيقات (API) معينة، دون الحاجة للوصول إلى الكود المصدري أو الاضطرار لفهم آليات عملها الداخلية. كما أنه يتيح للمطورين العمل مع واجهة برمجة التطبيقات (API)، بغض النظر عن اللغة التي كُتبت بها.

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

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

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

يمكن العثور على المواصفات الكاملة على GitHub.

باعتباره معياراً واقعياً في الصناعة، يوفر OpenAPI وثيقة آمنة، ومؤتمتة، ومفهومة على نطاق واسع لتطوير واجهات برمجة التطبيقات (APIs).

تم إنشاء OpenAPI في الأصل من قِبل المطور Tony Tam وتم إصداره لأول مرة في عام 2011 تحت اسم Swagger. في ذلك الوقت، غالباً ما كانت مواصفات واجهات برمجة التطبيقات (API) عبارة عن مستندات ثابتة تتطلب تحديثاً مملاً، وكثيراً ما كانت غير محدثة. تضمّنت مواصفات Swagger العديد من الابتكارات في مجال تطوير واجهات برمجة التطبيقات، بما في ذلك زر "جرّبها الآن" (try it out) لاختبار استدعاءات واجهة برمجة التطبيقات بشكل مباشر وفي الوقت الفعلي.

جعلت Swagger التوثيق محور وجودها. مكن ذلك المطورين من تضمين تعليقات توضيحية، مشابهة للملاحظات اللاصقة، في مصدر الرمز. يمكن لـ Swagger قراءة هذه التعليقات التوضيحية وتحديث الوثائق تلقائيًا، مما يضمن بقاء الوثائق محدثة دون الحاجة إلى أعمال تحديث مملة ومتكررة. كما قدّمتْ Swagger صيغةً لوصف واجهات برمجة التطبيقات (APIs) بتنسيق JSON المقروء آلياً، ممّا جعلها مستقلةً عن لغات البرمجة: فبغض النظر عن اللغة المستخدمة في الواجهة الخلفية، فإنّ Swagger تنتج ملف JSON موحداً.

تم الاستحواذ على Swagger من قِبل شركة SmartBear Software في عام 2015، وتمت إعادة تسميته إلى OpenAPI بعد فترة وجيزة، ثم تم التبرع به لمبادرة OpenAPI الجديدة (OAI) تحت مظلة مؤسسة Linux Foundation. الإصدار الحالي هو OpenAPI 3.1.

مواصفات OpenAPI هي وثيقة معيارية، قابلة للقراءة من قِبل البشر والآلات، تُحدد بنية واجهة برمجة التطبيقات وصيغتها. تتضمن جميع مستندات OpenAPI مكونات معينة وتتوافق مع البنية الأساسية نفسها، ولكن بعض المواصفات تحتوي على معلومات أكثر من غيرها. كحد أدنى، يجب أن تتضمن المواصفاتopenAPI وinfo حقول، واحد على الأقلpath ، component أو webhook حقل.¹

OpenAPI: تشير إلى إصدار OpenAPI الذي يستخدمه المستند، مثل "3.1.1"

المعلومات: تتضمن البيانات الوصفية العامة لواجهة برمجة التطبيقات (API)، مثل عنوان واجهة برمجة التطبيقات ورقم الإصدار، ووصفًا لواجهة برمجة التطبيقات، وشروط الخدمة، ومعلومات الاتصال. 

الخوادم: قائمة بعناوين URLs الأساسية التي يمكن من خلالها الوصول إلى واجهة برمجة التطبيقات (API) (والتي قد تشمل كلاً من بيئات التجريب والإنتاج). تتضمن هذه القائمة متغيرات خاصة بالبيئة المضيفة.

المسارات: تصف المسارات وأساليب HTTP المرتبطة بها (أو العمليات—على سبيل المثال: GET، PUT، POST) والمعاملات، وبنية الطلبات، والاستجابات الخاصة بكل عنصر من عناصر المسار.

المكونات: تسرد الكائنات القابلة لإعادة الاستخدام مثل المخططات، والمعاملات، والاستجابات، والترويسات (headers)، وتعرفيات الأمان. يمكن الرجوع إلى هذه الكائنات عبر المستند. يتم الرجوع إلى المكونات، بكل بساطة، باستخدام $ref. تحافظ هذه الاستراتيجية على تصميم واجهة برمجة التطبيقات (API) مبسطًا قدر الإمكان. 

الأمان: يحدد مخططات الأمان وآليات المصادقة التي تستخدمها واجهة برمجة التطبيقات (API)، مثل OAuth أو مفاتيح واجهة برمجة التطبيقات. كما أنه يتيح تطبيق مخططات الأمان بشكل عالمي، أو حسب كل عملية.

الوسوم (tags): قائمة رفيعة المستوى من الوسوم المستخدمة لتنظيم العمليات. يمكن استخدام الوسوم للمساعدة في تحسين وضوح المستند (على سبيل المثال، "المستخدمون" أو "الطلبات").

الوثائق الخارجية: روابط إلى الأدلة ووثائق الإعداد وغيرها من الوثائق الخارجية الخاصة بواجهة برمجة التطبيقات (API)

خطافات الويب (webhooks): تصف الاستدعاءات الواردة التي تتلقاها واجهة برمجة التطبيقات. 

يوفر OpenAPI مصدرا واحدا للحقيقة لمطوري ومستهلكي واجهات البرمجة (API)، ويوفر ميزات تضيف قيمة وكفاءة لمشاريع API.

تم إنشاء OpenAPI في البداية مع التركيز بشكل كبير على توثيق REST APIs، ولا يزال هذا التركيز يمثل جوهرها حتى اليوم. الوثائق موحدة، وتفاعلية، ومُحدّثة في الوقت الفعلي، وتوفر عقدًا بمثابة مصدر وحيد للحقيقة.

توجد أدوات متنوعة لقراءة وثائق OpenAPI وتصدير الكود. إحدى هذه الأدوات هي Swagger Codegen، والتي تقرأ المستندات المكتوبة وفقًا لمواصفات OpenAPI. يمكن لـ Swagger Codegen بعد ذلك إنتاج برمجيات مجموعات تطوير أدوات العميل لـ API، والبرمجيات الخاصة بالخادم (stubs)، وصفحات ويب مقروءة تحتوي على وثائق محدثة وسهلة القراءة للمستخدمين.

تظل ميزة زر "try it out" واحدةً من أكثر ميزات OpenAPI ابتكاراً، حيث تتيح إجراء الاختبار والتحقق في الوقت الفعلي مباشرةً من المتصفح. تُتيح أداة Swagger UI، وهي أداة مجانية ومفتوحة المصدر، واجهة مرئية تُمكِّن المطور من إرسال طلبات فعلية للمساعدة في ضمان استجابتها بالشكل المطلوب. تسهل هذه الأداة التحقق الفوري من أن الطلب يعمل.

يتم استخدام OpenAPI بشكل شائع مع منصات التكامل كخدمة، أو iPaaS.

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

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

تُعدّ حوكمة واجهات برمجة التطبيقات—وهي المعايير والسياسات والممارسات التي تُوجّه كيفية تطوير المؤسسة لواجهات برمجة التطبيقات واستخدامها—أمرًا حيويًا للمساعدة في ضمان عمل هذه الواجهات بسلاسة، وبشكل متسق، ودون تكرار غير ضروري. نظرًا لأن OpenAPI يعمل كعقد بين المطورين، يمكن تحقيق الحوكمة والأمان منذ البداية.

خذ على سبيل المثال بوابات واجهات برمجة التطبيقات (API gateways)، والتي تتولى مهامًا مثل توجيه حركة المرور، والمراقبة، وتحديد معدل الاستخدام. يمكن لبوابات واجهات برمجة التطبيقات عادةً أن تستهلك مواصفات OpenAPI وتفرض أي حدود لحركة المرور أو تدابير أمنية أخرى منصوص عليها في المواصفات.

الأمر نفسه ينطبق على قواعد الأمان. تتيح مواصفات OpenAPI للمطورين تحديد المتطلبات الأمنية (مثل استخدام OAuth 2.0 ومفاتيح واجهة برمجة التطبيقات، ويمكن فرض هذه المتطلبات لاحقًا في المراحل التالية (بواسطة البوابة، على سبيل المثال.)  يساعد تحديد ميزات الأمان في عقد واجهة برمجة التطبيقات (API) على ضمان عدم قيام المطورين بوضع مخططات أمان غير مدعومة.

يمكن لـ OpenAPI أن تُعزز إدارة واجهات برمجة التطبيقات، وهي العملية القابلة للتوسع لإنشاء اتصالات واجهة برمجة التطبيقات ونشرها وإدارتها، بطرق عدة. على سبيل المثال ، نظرًا لأن مواصفات OpenAPI قابلة للقراءة آليًا وموحدة، يمكن لبرامج الكتالوج والبوابة الإلكترونية فهرستها تلقائيًا. يعمل هذا التوحيد على تسهيل العثور على واجهات برمجة التطبيقات وفهمها عبر المؤسسة. تساعد قابلية الاكتشاف هذه على منع الفرق من بناء واجهات برمجة تطبيقات مكررة عن غير قصد.

يدعم OpenAPI أيضًا الإدارة والحوكمة المتسقة من خلال جعل المعايير التنظيمية واضحة وقابلة للتنفيذ. يمكن للفرق تحديد المتطلبات، مثل اتفاقيات إصدار النسخ، أو تنسيقات الاستجابة للأخطاء، أو أنماط التسمية، مباشرةً داخل المواصفات أو إلى جانبها. وبما أن هذه التوقعات موثقة بصيغة موحدة، فإنه يمكن التحقق من صحتها تلقائياً مقابل واجهات برمجة التطبيقات (APIs) الجديدة عند إضافتها. يُقلل هذا التدقيق من الاعتماد على المراجعة اليدوية، ويُساعِد في ضمان بقاء واجهات برمجة التطبيقات (APIs) متسقة مع نمو محفظة أعمال المؤسسة.