ما هو واجهة برمجة التطبيقات كاتو

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

نظرة عامة

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

نقطة نهاية ومخطط Cato API

عنوان URL لنقطة نهاية واجهة برمجة التطبيقات والمخطط محدد للموقع حيث تُستضاف نسخة تطبيق إدارة كاتو (CMA). يمكن أن يكون هناك قيمة <prefix> مضافة إلى عنوان URL لحساب CMA الخاص بك وإلى نقطة نهاية واجهة برمجة التطبيقات والمخطط.

عنوان URL لنقطة نهاية واجهة برمجة التطبيقات يكون بالتنسيق ، https://api.<prefix>.catonetworks.com/api/v1/graphql2.

عنوان URL لمخطط واجهة برمجة التطبيقات يكون بالتنسيق ، https://api.<prefix>.catonetworks.com/api/schema.

عناوين URL لنقطة نهاية واجهة برمجة التطبيقات

  • إذا لم يوجد بادئة (cc.catonetworks.com)، استخدم عنوان URL التالي: https://api.catonetworks.com/api/v1/graphql2

  • إذا كانت هناك بادئة (مثل cc.us1.catonetworks.com)، فستستخدم عنوان URL التالي (قم بتعديل البادئة لمواقع مختلفة): https://api.us1.catonetworks.com/api/v1/graphql2

عناوين URL للمخطط واجهة برمجة التطبيقات

  • إذا لم يوجد بادئة (cc.catonetworks.com)، استخدم عنوان URL التالي: https://api.catonetworks.com/api/schema

  • إذا كانت هناك بادئة (مثل cc.us1.catonetworks.com)، فستستخدم عنوان URL التالي (قم بتعديل البادئة لمواقع مختلفة): https://api.us1.catonetworks.com/api/schema

توثيق مخطط API

واجهات برمجة التطبيقات كاتو تعتمد على GraphQL، وتوفر واجهة بديهية تتوافق بشكل كامل مع أدوات العملاء API ذات الطراز RESTful. توفر GraphQL أيضًا المرونة الإضافية للاستعلام عن البيانات التي تحتاجها، مما يقلل من الاستخراج الزائد ويحسن الكفاءة.

توثيق واجهة برمجة التطبيقات كاتو متاح في مرجع GraphQL لواجهات برمجة التطبيقات كاتو، والذي يحتوي على:

  • تعريف المخطط والتوثيق

  • أمثلة على استدعاءات واجهة برمجة التطبيقات والاستجابات النموذجية المقابلة

  • نقطة نهاية واجهة برمجة تطبيقات GraphQL مع بيئة لعب تفاعلية لاستكشاف واجهة برمجة التطبيقات واختبارها

دورة حياة API

تصف هذه القسم مراحل دورة الحياة المختلفة بناءً على مستوى النضج وتوافر واجهة برمجة التطبيقات المحددة.

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

ملاحظة

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

على سبيل المثال، لا يغطي الأمثلة والأدوات مفتوحة المصدر المتاحة في حساب كاتو على GitHub. تُقدم هذه الموارد "كما هي" بدون ضمان أو التزام بتطوير أو صيانة أو دعم إضافي.

مستويات نضج API

هذه هي مستويات نضج واجهة برمجة التطبيقات كجزء من مرحلة دورة الحياة:

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

  • GA (التوافر العام): واجهات برمجة التطبيقات في حالة GA مستقرة وجاهزة للإنتاج وتأتي مع دعم طويل الأمد والالتزامات بالتوافق مع الإصدارات السابقة. التغييرات الكبيرة في مخطط واجهة برمجة التطبيقات نادرة وتُعلن عنها بفترة مناسبة مقدمًا لتوفير وقت كافٍ لتعديل رموز العميل.

    تُعتبر واجهات برمجة التطبيقات التي لم يتم تصنيفها بوضوح كـ Beta بمثابة GA. في بعض الحالات، ضمن واجهة برمجة تطبيقات GA، قد يتم تصنيف الحقول الفردية والأنواع والمدخلات كـ Beta.

مستويات توفر API

هذه هي مستويات توافر واجهات برمجة التطبيقات كجزء من مرحلة دورة الحياة:

  • EA (التوافر المبكر): تُتاح واجهات برمجة التطبيقات في EA لمجموعة محدودة من المستخدمين للاختبار والحصول على الملاحظات قبل الإطلاق الأوسع. قد يتطلب الوصول موافقة أو شروط خاصة.

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

    تعتبر واجهات برمجة التطبيقات التي لم يتم تصنيفها كـ EA أو إطلاق تدريجي مُمثلة للتوزيع الكامل ومتاحة لجميع المستخدمين.

ملخص تسميات API

يُلخص هذا القسم التصنيفات المستخدمة لواجهات برمجة التطبيقات في الوثائق بناءً على مستويات النضج والتوفر.

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

  • EA

    • متاح فقط للعملاء الذين ينضمون إلى برنامج Cato EA، للانضمام، يرجى الاتصال بنا على ea@catonetworks.com

  • بيتا

    • قد يكون هناك تغييرات على المخطط

    • إشعار محدود للتغييرات الكسرية، ربما قصير لمدة تصل إلى أسبوعين

    • واجهات برمجة التطبيقات Beta تدعم الوظيفة الكاملة

  • إطلاق تدريجي

    • يتم إطلاق هذه واجهات برمجة التطبيقات GA تدريجيًا لجميع الحسابات على مدى بضعة أسابيع

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

التغييرات المحتملة في مخطط الكسر

يتناول هذا القسم الحالات التي تقوم فيها كاتو بإجراء تغييرات على مخطط واجهة برمجة التطبيقات GraphQL التي يمكنها التأثير على السلوك والنتائج لاستدعاءات واجهات برمجة التطبيقات.

ما هو التغيير المحتمل في GraphQL؟

يحدث تغيير محتمل الكسر في GraphQL عندما تجبر تعديلات في واجهة برمجة التطبيقات تطبيقات العميل على تحديث استفساراتهم أو منطقهم للحفاظ على الوظيفة. تشمل الأمثلة:

  • إزالة حقل، نوع، أو وسيط.

  • إعادة تسمية حقول، أنواع، أو وسائط.

  • تعديل القيم الافتراضية للوسائط بطريقة تغيّر النتائج المتوقعة للاستعلامات أو التغييرات.

  • تغيير نوع أو سلوك الحقل بطريقة تؤثر على التوافق. على سبيل المثال، تغيير نوع الحقل (مثل، من Int إلى String) أو تعديل عدم إمكانية وسيط (مثل، من قابل للإلغاء إلى غير قابل للإلغاء).

إعلان وإدارة التغييرات المحتملة

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

قد تحدث هذه التغييرات بشكل أكثر تكرارًا لواجهات برمجة التطبيقات Beta ولكنها نادرة لواجهات برمجة التطبيقات GA.

APIs المتوقفة

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

الإخطار حول APIs التي وصلت إلى نهاية الحياة

إذا كان من المقرر إزالة واجهة برمجة التطبيقات أو الحقل أو تغييره، فستمر بعملية إنهاء العمر الافتراضي (EoL). تشمل هذه العملية الخطوات التالية:

  1. وضع علامة على واجهة برمجة التطبيقات أو الحقل كمهمل

    1. واجهة برمجة التطبيقات أو الحقل المقرر إزالته يتم وضع علامة عليه كـ مهمل في مرجع واجهة برمجة التطبيقات كاتو GraphQL.

    2. ترافق هذه العلامة رسالة، تحدد واجهة برمجة تطبيقات أو حقل بديل إذا كان ينطبق، وتاريخ إنهاء العمر الافتراضي المخطط له.

  2. إشعارات نهاية العمر الافتراضي

    1. تم تحديث مقال Cato API Potentially Breaking Changes and EoL بتاريخ محدد لتحديث المخطط بالتغيير.

    2. الفترة الزمنية بين الإشعار وتغييرات المخطط هي كما يلي:

      • واجهة برمجة التطبيقات GA: على الأقل 3 أشهر مقدماً وعادةً 6 أشهر مقدماً

      • واجهة برمجة التطبيقات Beta: عادةً 2 أسبوعين مقدماً

    3. خلال الفترة الزمنية بين إشعار نهاية العمر الافتراضي وتاريخ نهاية العمر الافتراضي، يُتوقع أن يقوم العملاء بتحديث كود العميل لاستيعاب التغييرات في مخطط GraphQL.

التغييرات غير الكاسرة في المخطط

التغييرات على GraphQL التي ليست كاسرة ولكنها لا تزال مهمة، مثل APIs جديدة أو حقول جديدة، يتم الإعلان عنها في مقال Cato API Changelog.

يتضمن مرجع واجهة برمجة التطبيقات كاتو GraphQL دائمًا المخطط الكامل المدعوم والمحدث.

هل كان هذا المقال مفيداً؟

0 من 0 وجدوا هذا مفيداً

لا توجد تعليقات