العملية الكاملة لإنتاج واجهة برمجة التطبيقات (API) من الصفر متعبة للغاية. بدءًا من سؤال "ماذا يجب أن تهدف واجهة برمجة التطبيقات الخاصة بي للقيام به؟"، تلاها جميع كتابة الشيفرة والاختبار، لقد وصلت أخيرًا إلى نهاية دورة تطوير واجهة برمجة التطبيقات الأولى - النشر.
ما هي وثائق واجهة برمجة التطبيقات ولماذا هي مهمة
عند إطلاق واجهة برمجة التطبيقات الخاصة بك على الإنترنت وجعلها متاحة للمطورين لتنفيذها في تطبيقاتهم، يتعين عليك رد على سؤال سيسأله الجميع. سيستفسر المطورون على الفور عن كيفية استخدام واجهة برمجة التطبيقات الخاصة بك.
لهذا السبب تعتبر وثائق واجهة برمجة التطبيقات - الجيدة منها - مفيدة للغاية ليس لك فقط، بل للجميع الذين لديهم اهتمام بواجهة برمجة التطبيقات الخاصة بك. أفضل وثائق واجهة برمجة التطبيقات هي تلك التي يمكن للمطورين فهمها دون استشارةك، صانع واجهة برمجة التطبيقات، حيث يمكنهم اكتساب كل المعرفة المطلوبة من الوثائق.
نظرة عامة على وثائق REST API
REST (نقل حالة التمثيل) هو مصطلح يُستخدم لوصف الأسلوب المعماري الذي تتبعه واجهة برمجة التطبيقات.
السبب في أن هذه المقالة تركز على REST API هو أن REST API هي واحدة من أكثر أنواع واجهات برمجة التطبيقات ترحيبًا، ومعروفة بشكل رئيسي لتبسيط التواصل بين تطبيقات الويب. تُستخدم واجهات REST API بشكل رئيسي في عمليات الخلفية على جانب الخادم من التطبيق.
نصائح لكتابة وثائق REST API
واجهات REST API ليست متشابهة مع أي واجهات برمجة تطبيقات أخرى. بالطبع، لديهم متغيرات مشابهة مثل طرق HTTP والمعلمات، ولكن تمتلك واجهات REST API بعض الخصائص الفريدة. ستحتاج وثائق REST API الخاصة بك إلى تعديلات لتغطية هذه الاختلافات وشرحها.
بسيطة لكنها مفيدة
قد يكون لدى الجميع بمختلف المهارات اهتمام في واجهة برمجة التطبيقات الخاصة بك، لذا اكتب وثائق REST API الخاصة بك بطريقة تلبي معرفة الجميع حول واجهات برمجة التطبيقات. حاول تجنب المصطلحات الفنية حيث أن المفردات الفنية قد تكون صعبة الفهم بالنسبة لمعظم القراء.
حالات الاستخدام الشائعة
مع وجود واجهات REST API ذات المعمارية المميزة، فإنها أيضًا تتخصص في جوانب معينة من البرمجيات: نقل البيانات. مع توجيه معظم واجهات REST API للمعالجة الداخلية للبيانات، من الجيد توفير بعض حالات الاستخدام لإظهار وظيفة واجهة برمجة التطبيقات الخاصة بك.
بروتوكول HTTP
تجري واجهات REST API جميع اتصالاتها من خلال بروتوكول HTTP، على عكس واجهات الويب الأخرى التي يمكن أن تستخدم بروتوكول HTTP وHTTPS. تستخدم واجهات REST API أيضًا طرق HTTP لنقل المعلومات بين العملاء والخوادم، مما يعني أنه من الأفضل توضيح الأفعال المستخدمة من HTTP (GET، POST، PUT، أو DELETE).
كيفية كتابة وثائق RESTful API
قد يبدو إنشاء وثائق واجهة برمجة التطبيقات الفعالة معقدًا، ومع ذلك، تتوفر العديد من أدوات وثائق واجهة برمجة التطبيقات للجميع للاستخدام. بالإضافة إلى ذلك، توفر معظم منصات واجهة برمجة التطبيقات، مثل Swagger، Postman، وApidog أيضًا مولدات للوثائق لإنشاء وثائق واجهة برمجة التطبيقات.
يمكن للتطبيقات الثلاثة المذكورة (المعروفة أيضًا بمنصات واجهة برمجة التطبيقات) أن تتشارك في إنشاء وثائق واجهة برمجة التطبيقات المقابلة أثناء تطوير واجهة برمجة التطبيقات نفسها. لم تعد بحاجة إلى إعادة إنتاج العملية بأكملها والتفاصيل المتعلقة بواجهات برمجة التطبيقات التي قمت بإنشائها!
استخدام Apidog لإنشاء وثائق REST API بسهولة
Apidog هي أداة جديدة ولكنها قوية وفعالة جدًا لتطوير واجهة برمجة التطبيقات. منصة واجهة برمجة تطبيقات بديهية جدًا، يمكن للمستخدمين فهم كيفية إنشاء وثائق REST API بسهولة أثناء العمل على مشاريعهم. ولكن قبل أن تبدأ تجربتك مع Apidog، تأكد من تنزيل تطبيق Apidog أولاً.
للبدء باستخدام Apidog، اتبع الخطوات أدناه:
الخطوة 1 - إنشاء حساب Apidog
أولاً، ابدأ باختيار طريقة لإنشاء حساب Apidog الخاص بك. يمكنك الاختيار من بين ثلاث طرق: حساب Google أو حساب GitHub أو حساب البريد الإلكتروني. التسجيل في Apidog مجاني، ولا تتطلب معلومات شخصية إضافية مثل تفاصيل بطاقة الائتمان في التسجيل.
الخطوة 2 - إنشاء مشروع REST API جديد في Apidog
بمجرد تسجيل الدخول إلى حساب Apidog الخاص بك، يجب أن تكون قادرًا على رؤية الشاشة أعلاه. لإنشاء مجلد حصري لمشروع واجهة برمجة التطبيقات الخاصة بك، اضغط على زر "مشروع جديد" الموجود في الزاوية العليا اليمنى من نافذة تطبيق Apidog، وسمي المشروع وفقًا لما خططت له.
الخطوة 3 - إنشاء واجهة برمجة التطبيقات جديدة في مشروع Apidog الخاص بك
إدخال التفاصيل الضرورية حول واجهة برمجة التطبيقات الخاصة بك
بينما تبدأ من الصفر، ابدأ بإنشاء واجهة برمجة تطبيقات جديدة.
في هذه العملية من تطوير واجهة برمجة التطبيقات الخاصة بك، تأكد من أن تكون كاملاً وكفئًا مع التفاصيل حول واجهة برمجة التطبيقات الخاصة بك. كن مختصرًا ولكن فكر في نوع القراء المحتملين الذين قد تجذبهم واجهة برمجة التطبيقات REST الخاصة بك. املأ أكبر عدد ممكن من الحقول الفارغة، لأنها ستصبح جزءًا تلقائيًا من وثائق واجهة برمجة التطبيقات التي ينتجها Apidog.
إذا كنت غير متأكد من كيفية كتابة وثائق API، خذ وقتك وخصص بعض الوقت لقراءة المزيد حول ما هو متوقع. قد يساعدك سؤال صديق أيضًا!
احفظ تقدم عملك
بعد العمل على واجهة برمجة التطبيقات الخاصة بك أو كلما كنت تعتقد أنك بحاجة إلى أخذ استراحة من العمل، تأكد من حفظ تقدمك بالضغط على زر "حفظ" الموجود في الزاوية العليا من الشاشة!
الخطوة 4 - مشاركة وثائق REST API الخاصة بك
السهم 1 - ابدأ بالبحث عن الضغط على زر "مشاركة"، الموجود على الشريط العمودي في الجانب الأيسر من نافذة التطبيق Apidog. يجب أن تكون قادرًا الآن على رؤية صفحة "المستندات المشتركة"، والتي يجب أن تكون فارغة.
السهم 2 - اضغط على زر "+ جديد" أسفل "لا توجد بيانات" لبدء إنشاء أول وثائق REST API لـ Apidog.
حدد وضمن خصائص وثائق واجهة برمجة التطبيقات المهمة
هل ترغب في نشر واجهة برمجة التطبيقات على الإنترنت؟ هل واجهة برمجة التطبيقات مخصصة فقط لشركتك، أم أنها مشروع صغير لديك لنفسك؟ يحتوي Apidog على خيار لاختيار من يمكنه عرض وثائق واجهة برمجة التطبيقات الخاصة بك، بالإضافة إلى تعيين كلمة مرور للملف، بحيث لا يمكن إلا للأفراد أو المنظمات المختارة عرضها.
بمجرد تضمين معلومات الوثيقة الأخرى مثل اسم وثيقة واجهة برمجة التطبيقات واللغة، يمكنك الضغط على زر "إدخال" على لوحة المفاتيح الخاصة بك، أو زر "حفظ" الموجود في أسفل الشاشة الحالية.
عرض أو مشاركة وثائق REST API الخاصة بك
يمكنك الآن أن تقرر ماذا تفعل بوثائق واجهة برمجة التطبيقات الخاصة بك. يقوم Apidog بتجميع تفاصيل مشروع واجهة برمجة التطبيقات الخاصة بك في وثيقة واجهة برمجة التطبيقات التي يمكن عرضها من خلال عنوان URL للموقع. كل ما عليك فعله هو الضغط على رابط "نسخ الرابط" تحت "الإجراءات"، ويمكنك نسخه ولصقه في متصفح الويب الخاص بك لرؤيته.
في أي حال تحتاج إلى المزيد من التفاصيل، اقرأ هذه المقالة حول كيفية إنشاء وثائق واجهة برمجة التطبيقات باستخدام Apidog.
إنشاء وثائق REST API باستخدام Swagger
مثل Apidog، يسهل أيضًا Swagger على مطوري واجهات برمجة التطبيقات أو الكتّاب وثيقتهم. لتحرير الأجزاء الأساسية الأكثر أهمية من وثائق واجهة برمجة التطبيقات باستخدام Swagger، اتبع التفاصيل أدناه.
السهم 1 - الجزء العلوي من الجانب الأيسر من محرر Swagger (الذي يبدو أكثر كرمز) هو المكان الذي يمكنك فيه تحرير وصف واجهة برمجة التطبيقات. تأكد من أنك تقدم وصفًا واضحًا وبسيطًا ليفهمه القراء من خلال تضمين وظيفة واجهة برمجة التطبيقات، بالإضافة إلى عدة معلمات وحالات استخدام شائعة.
السهم 2 - يسمح لك الجزء السفلي المظلل بإجراء تغييرات على الجزء الفني والصديق للقراء في وثائق واجهة برمجة التطبيقات. هذا هو المكان الذي يمكنك فيه تحرير طريقة واجهة برمجة التطبيقات والمعلمات وأمثلة الرموز.
يمكنك أيضًا معرفة تفاصيل أفضل حول كيفية استخدام Swagger لوثائق REST API هنا.
توثيق واجهات REST API باستخدام Postman
يوفر Postman واجهة مستخدم أكثر ودية، حيث الجانب الأيمن المظلل مخصص لأي معلومات إضافية حول REST API في التطوير. هناك 4 أقسام يمكن لمطوري REST API تحريرها لعرض المزيد من التفاصيل حول واجهة برمجة التطبيقات.
- الوثائق - يجب عليك إدخال جميع المعلومات الهامة حول واجهة برمجة التطبيقات الخاصة بك، مثل حالات الاستخدام الشائعة، ومقدمة موجزة عن نوع المدخلات والمخرجات المتوقعة، بالإضافة إلى وصف لفائدتها.
- التعليقات - على Postman، يمكنك مشاركة وثائق واجهة برمجة التطبيقات الخاصة بك ليستخدمها الجمهور ويقرأها، والحصول على ملاحظات أو انتقادات بشأن وثائق REST API الخاصة بك. إنها نقطة إيجابية جدًا في Postman، حيث من الصعب جدًا الحصول على واجهة برمجة تطبيقات مثالية مباشرة من الإنتاج.
- قصاصات الشيفرة - يتيح لك Postman إعداد عينات الشيفرة للمطورين لاختبار واجهة برمجة التطبيقات الخاصة بك. يمكنك إعداد قصاصات الشيفرة لأكثر من عشرة لغات عميل، لذا قم بإعداد أكبر عدد ممكن!
- معرف الطلب - كما ذكر Postman، يمكن أن يكون عنصر Postman أي شيء من طلب HTTP إلى واجهة برمجة التطبيقات نفسها، هذا القسم هو المكان الذي يمكن للمطورين فيه العثور على معرف الطلب المحدد لواجهة برمجة التطبيقات REST الخاصة بك.
ابدأ إنشاء وثائق واجهة برمجة التطبيقات الخاصة بك
على الرغم من أن بعض منصات واجهات برمجة التطبيقات مثل Apidog، وSwagger، وPostman قد تساعدك في إنشاء وثائق واجهة برمجة التطبيقات بشكل أفضل، ما يهم أكثر هو أن تكون جوانب معينة وحاسمة من وثائق واجهة برمجة التطبيقات موجودة. اللغة البسيطة، حالات الاستخدام الشائعة، وبروتوكول HTTP المباشر ضرورية لفهم المطور لواجهة برمجة التطبيقات الخاصة بك!