دليل API Blueprint - دليل لفهم واجهات برمجة التطبيقات بالكامل

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

ستقدم هذه المقالة أداة قوية تُستخدم لوصف وتوثيق واجهات برمجة التطبيقات على الويب مع نهج يركز على التصميم، تُسمى API Blueprint.

ما هي API Blueprint؟

الرابط: https://apiblueprint.org/

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

الميزات الرئيسية لـ API Blueprint

هناك بعض الأمور التي تتفوق فيها API Blueprint، بشكل رئيسي لهذه الخصائص:

التواصل والتعاون

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

نهج تصميم أولاً

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

التركيز على التوثيق

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

ميزات إضافية

• نظام أدوات: تدعم أدوات متنوعة مثل Apiary وAglio تطوير API Blueprint، موفرة وظائف مثل التصور وتوليد الوثائق.
• أساس للاختبار: تعتبر مخططات واجهة برمجة التطبيقات أساسًا لاختبار واجهات برمجة التطبيقات من خلال تحديد السلوكيات المتوقعة والردود.
• مرونة: بينما تركز بشكل أساسي على واجهات برمجة التطبيقات التي تعمل بأسلوب RESTful، يمكن تكييف مخططات واجهة برمجة التطبيقات لأنماط واجهة برمجة التطبيقات الأخرى أيضًا.

كيف تستخدم API Blueprint؟

أولاً، ستحتاج إلى وجود محرر نصوص عادي جاهز، وإذا كان متاحًا، قم بتبديل تلوين الصيغة إلى Markdown أو مباشرة إلى API Blueprint إذا كانت مدعومة.

إذا كنت لا تزال تبحث عن محرر نصوص عادي، يمكنك الاطلاع على قائمة المحررين الموصى بهم، وتأكد من تخصيص وقتك للتعرف على المحرر الذي اخترته!

بعد ذلك، عليك أن تتعلم الأساسيات النحوية لـ API Blueprint. حيث تستفيد API Blueprint من Markdown لهيكلها وقابلية قراءتها، ومع MSON لتعريف هياكل البيانات، سيتعين عليك الرجوع إلى الموقع الرسمي لـ API Blueprint للحصول على المزيد من الدروس والمراجع.

هل API Blueprint مجانية؟

نعم، نظرًا لأن API Blueprint هي أداة مفتوحة المصدر يمكنك العثور عليها على GitHub، يمكن لأي شخص البدء في استخدام API Blueprint دون دفع أي سنت!

هل أحتاج إلى تثبيت أي تطبيقات أخرى؟

بعيدًا عن محرر النصوص، قد ترغب في التفكير في تثبيت أدوات أخرى تعمل جيدًا مع API Blueprint. لرؤية القائمة الكاملة للأدوات المتوافقة مع API Blueprint، يمكنك الاطلاع على قائمة الأدوات الموصى بها.

أمثلة على كود API Blueprint

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

العينة 1 - مورد بسيط مع إجراء GET:

# واجهة برمجة التطبيقات البسيطة الخاصة بي

توفر هذه واجهة برمجة التطبيقات الوصول إلى قائمة من المستخدمين.

## المستخدمون

مجموعة من كائنات المستخدم.

### GET /users

تسترجع قائمة بكل المستخدمين.

تعود:

* الحالة: 200 حسنًا
* نوع المحتوى: application/json

تحدد عينة الكود أعلاه واجهة برمجة تطبيقات بسيطة مع مورد واحد يُسمى Users، والتي تسمح بطلب GET إلى /users لاسترجاع قائمة بكل المستخدمين. تحدد قسم الاستجابة رمز الحالة النجاح 200 حسنًا ونوع المحتوى (JSON) لهيئة الاستجابة.

العينة 2 - مورد مع إجراءات متعددة:

## المنتجات

مجموعة من كائنات المنتج.

### GET /products

تسترجع قائمة بكل المنتجات.

تعود:

* الحالة: 200 حسنًا
* نوع المحتوى: application/json

### GET /products/{id}

تسترجع منتجًا معينًا بواسطة الهوية الخاصة به.

معلمات المسار:

* id (سلسلة) - المعرف الفريد للمنتج.

تعود:

* الحالة: 200 حسنًا
* نوع المحتوى: application/json

توسع هذه العينة على مفهوم الموارد من خلال إظهار كيفية تحديد إجراءات متعددة (GET) لمورد واحد Products. إجراء واحد يسترجع جميع المنتجات، بينما يسترجع الآخر منتجًا معينًا بناءً على المعرف الخاص به المحدد كمعلمة مسار.

العينة 3 - هياكل البيانات مع MSON:

## المستخدمون

مجموعة من كائنات المستخدم.

**مستخدم**

{
	"id": "string",
	"name": "string",
	"email": "string"
}
### GET /users

تسترجع قائمة بكل المستخدمين.

تعود:

* الحالة: 200 حسنًا
* نوع المحتوى: application/json

استجابة:

```json
[
  {
    "id": "user-1",
    "name": "جون دو",
    "email": "[عنوان البريد الإلكتروني محذوف]"
  },
  {
    "id": "user-2",
    "name": "جين سميث",
    "email": "[عنوان البريد الإلكتروني محذوف]"
  }
]

توضح عينة الكود أعلاه تعريف هيكل بيانات باسم User باستخدام صيغة MSON. Specifies the properties and their data types within the user object.

كما تتضمن قسم الاستجابة مثالًا على حزمة JSON تتبع الهيكل الهيكلي المعرفة.

Apidog - أداة تطوير واجهة برمجة التطبيقات الشاملة

بعيدًا عن API Blueprint، هناك أداة تطوير واجهة برمجة تطبيقات أخرى مزودة لجميع دورة حياة واجهة برمجة التطبيقات - Apidog. Apidog هي منصة واجهة برمجة تطبيقات تتمتع بواجهة مستخدم بديهية وبسيطة، مصممة لمساعدة المستخدمين الجدد على التكيف بسرعة مع بيئة العمل الجديدة.

مع Apidog، يمكنك بناء، وتقليد، واختبار، وتوثيق واجهات برمجة التطبيقات كلها داخل النظام الأساسي. لرؤية كيفية عمل Apidog، تأمل الأقسام أدناه!

بناء واجهة برمجة التطبيقات الجديدة الخاصة بك مع Apidog

مع Apidog، يمكنك إنشاء واجهات برمجة التطبيقات بنفسك. قد يوفر عليك أيضًا الوقت - دون الحاجة إلى البحث بلا نهاية على الإنترنت للعثور على "الإجابة الصحيحة"، يمكنك ببساطة إنشاؤها بنفسك.

ابدأ بالضغط على زر New API، كما هو موضح في الصورة أعلاه.

بعد ذلك، يمكنك اختيار العديد من خصائص واجهة برمجة التطبيقات. في هذه الصفحة، يمكنك:

• تعيين طريقة HTTP (GET، POST، PUT، أو DELETE)
• تعيين عنوان URL لواجهة برمجة التطبيقات (أو نقطة النهاية لواجهة برمجة التطبيقات) لتفاعل العميل والخادم
• تضمين معلمة واحدة/متعددة يجب تمريرها في عنوان URL لواجهة برمجة التطبيقات
• تقديم وصف للوظائف التي تهدف واجهة برمجة التطبيقات لتوفيرها.

لتقديم بعض المساعدة في إنشاء واجهات برمجة التطبيقات في حال كنت هذه هي المرة الأولى التي تقوم فيها بإنشائها، قد تفكر في قراءة هذه المقالات لفهم أفضل الممارسات لصنع واجهات برمجة التطبيقات على نمط REST (أو واجهات برمجة التطبيقات بشكل عام):

توليد وثائق معلوماتية لنقاط نهاية واجهة برمجة التطبيقات باستخدام Apidog

بالمثل، مع API Blueprint، يمكن لـ Apidog توليد وثائق جميلة ومعلوماتية لواجهة برمجة التطبيقات بناءً على ما قمت بتصميمه وتضمينه خلال مرحلة تطوير واجهة برمجة التطبيقات.

السهم 1 - أولاً، اضغط على زر Share في الجانب الأيسر من نافذة تطبيق Apidog. يجب أن تكون قادرًا على رؤية صفحة "المستندات المشتركة"، التي يجب أن تكون فارغة.

السهم 2 - اضغط على زر + New تحت No Data لبدء إنشاء أول وثائق واجهة برمجة التطبيقات الخاصة بك في Apidog.

حدد وتضمن خصائص وثائق واجهة برمجة التطبيقات المهمة

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

عرض أو مشاركة وثائق واجهة برمجة التطبيقات الخاصة بك

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

إذا كانت هناك حاجة لمزيد من التفاصيل، اقرأ هذه المقالة حول كيفية توليد وثائق واجهة برمجة التطبيقات باستخدام Apidog:

الخاتمة

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

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

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