تعد واجهة برمجة التطبيقات جيدة مثل التوثيق الخاص بها ، لذا تأكد من إمكانية اكتشافها من خلال إرشادات عالية الجودة وتفاصيل مهمة أخرى.
تستفيد المزيد من المؤسسات من قوة واجهات برمجة التطبيقات لتحسين أعمالها. أصبحت واجهات برمجة التطبيقات وسيلة لإلغاء تأمين القيمة وتقديم خدمة إضافية.
على الرغم من شعبيتها العامة ، ليس كل API ناجحًا. إن اعتماد واستخدام API إلى حد كبير يحدد نجاحها. لزيادة الاعتماد ، يجب أن يكون من السهل العثور على واجهة برمجة التطبيقات واستخدامها.
أفضل طريقة للقيام بذلك هي توثيق API الخاص بك بالتفصيل. يتضمن ذلك تفصيل المكونات الهامة لتسهيل فهمها. اكتشف بعض المكونات التي يجب عليك تضمينها في وثائق API الخاصة بك.
ما هو توثيق API؟
وثائق API هي محتوى تقني يصف API بالتفصيل. إنه دليل يحتوي على جميع المعلومات المطلوبة للعمل مع واجهة برمجة التطبيقات. يغطي المستند دورة حياة API وإرشادات حول تكامل واستخدام مكوناته.
تغطي وثائق API أوصاف الموارد ونقاط النهاية والأساليب والطلبات وأمثلة الاستجابة. يمكن أن تتضمن أيضًا أدلة عملية ودروسًا توضح للمستخدمين كيفية دمجها. يمنح استكشاف كل قسم للمستخدمين فهمًا قويًا لدمج واستخدام واجهة برمجة التطبيقات.
تم استخدام المحررين مثل محرر مستندات Google على نطاق واسع لتوثيق واجهة برمجة التطبيقات الاحترافية. في الوقت الحاضر ، هناك أدوات أكثر تقدمًا مثل Document 360 و Confluence و GitHub Pages. تساعد هذه الأدوات على دمج النص والتعليمات البرمجية لتسهيل سير العمل.
1. نظرة عامة والغرض من API
الخطوة الأولى في توثيق واجهة برمجة التطبيقات هي السماح للمستخدمين بمعرفة ما تدور حوله. قم بتضمين معلومات حول نوع الموارد التي يوفرها. عادةً ما تحتوي واجهات برمجة التطبيقات على موارد مختلفة تقوم بإعادتها ، بحيث يمكن للمستخدم طلب ما يحتاج إليه.
الوصف موجز ، وعادة ما يكون من جملة إلى ثلاث جمل تصف المصدر. صِف المورد المتاح ونقاط النهاية والطرق المرفقة بكل نقطة نهاية. بصفتك مطور واجهة برمجة التطبيقات ، فأنت أفضل وصف لمكوناته ووظائفه وحالة استخدامه.
فيما يلي مثال على وصف Airbnb API:
2. طرق المصادقة والترخيص
تتعامل واجهات برمجة التطبيقات مع آلاف الطلبات وكميات هائلة من البيانات. المصادقة هي إحدى الطرق لضمان حماية بيانات واجهة برمجة التطبيقات والمستخدمين من المتسللين. تتحقق مصادقة API من هوية المستخدم ويمنحهم إمكانية الوصول إلى الموارد.
هناك عدة طرق للتأكد أمن نقطة النهاية. تستخدم معظم واجهات برمجة التطبيقات مفتاح API. هذه سلسلة من الأحرف يمكن للمستخدم إنشاؤها من موقع الويب واستخدامها للمصادقة.
يجب أن توجه وثائق API المستخدمين حول كيفية مصادقة وتفويض هوياتهم. يعرض الرسم البياني التالي معلومات مصادقة Twitter API.
3. نقاط النهاية وأنماط URI وطرق HTTP
في هذا القسم ، وضح كيفية الوصول إلى المورد. تظهر نقاط النهاية فقط نهاية المسار ، ومن هنا جاءت تسميتها. أنها تظهر الوصول إلى المورد و طرق HTTP تتفاعل نقطة النهاية مع ، أي GET أو POST أو DELETE.
من المحتمل أن يحتوي أحد الموارد على مجموعة متنوعة من نقاط النهاية. لكل منها مسار وطريقة مختلفة. عادةً ما تحتوي نقاط النهاية على أوصاف موجزة للغرض منها ونمط عنوان URL.
يُظهر نموذج التعليمات البرمجية التالي نقطة نهاية مستخدم GET على Instagram.
امسك بي؟ الحقول = {الحقول} & access_token = {access-token}4. تنسيقات الطلب والاستجابة
يجب عليك توثيق تنسيقات الطلب والاستجابة حتى يعرف المستخدم ما يمكن توقعه. الطلب عبارة عن عنوان URL من عميل يطلب موردًا ، في حين أن الاستجابة عبارة عن تعليقات من الخادم.
ما يلي هو نموذج طلب يمكنك إرساله إلى LinkedIn API.
يحصل https://api.linkedin.com/v2/{service}/1234وإليك عينة من الاستجابة يمكن إرجاعها:
{
"المعرف": 1234 ،
"relatedEntity": "urn: li: relatedEntity: 6789"
}5. المعلمات والرؤوس
يجب عليك أيضًا توثيق معلمات نقاط النهاية الخاصة بك ، وهي خيارات يمكنك تمريرها إليها. يمكن أن تكون المعلمات معرفًا أو رقمًا يحدد مقدار أو نوع البيانات التي يتم إرجاعها استجابةً.
هناك أنواع مختلفة من المعلمات ، بما في ذلك معلمات سلسلة الرأس والمسار والاستعلام. يمكن أن تحتوي نقاط النهاية على أنواع مختلفة من المعلمات.
يمكنك تضمين بعض المعلمات كرؤوس طلبات HTTP. عادةً ما تكون هذه لأغراض المصادقة مثل مفتاح API. فيما يلي مثال على رأس بمفاتيح API:
الرؤوس: {
"X-RapidAPI-Key": "fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635" ،
"X-RapidAPI-Host": "wft-geo-db.p.rapidapi.com"
}
تقوم بتضمين معلمات المسار في نص نقطة النهاية مباشرةً على عنوان URL. تُظهر للمستخدم كيف وأين يتم وضع المعلمات وكيف ستظهر الاستجابة. الكلمات الموجودة في الأقواس المتعرجة هي معلمات.
يمكنك أيضًا استخدام النقطتين أو صيغ أخرى لتمثيل معلمات المسار.
/service/myresource/user/{user}/bicycles/{bicycleId}باستخدام معلمات الاستعلام ، يجب عليك وضع علامة استفهام (؟) قبل الاستعلام على نقطة نهاية. افصل كل معلمة بعد ذلك بعلامة العطف (&). لدى Microsoft وثائق جيدة حول Graph API.
6. أكواد الخطأ ومعالجة الخطأ
في بعض الأحيان تفشل طلبات HTTP ، مما قد يترك المستخدم في حيرة من أمره. قم بتضمين أكواد الخطأ المتوقعة في الوثائق لمساعدة المستخدمين على فهم الأخطاء.
يوفر LinkedIn رموز خطأ HTTP قياسية لمعالجة الأخطاء:
7. عينة من مقتطفات التعليمات البرمجية
تعتبر مقتطفات التعليمات البرمجية أجزاء أساسية من وثائقك. يوضحون للمستخدمين كيفية دمج واجهة برمجة التطبيقات بلغات وأشكال مختلفة. قم بتضمين كيفية تثبيت SDK ودمجها (مجموعات تطوير البرامج) بلغات مختلفة في الوثائق.
يحتوي RapidAPI على أمثلة جيدة لمقتطفات التعليمات البرمجية للمطورين:
9. إصدارات API وتغيير السجلات
تعد إصدارات API جزءًا أساسيًا من تصميم API. يضمن تقديم خدمات دون انقطاع للمستخدمين. يمكن أن يؤدي تعيين الإصدار إلى تحسين واجهة برمجة التطبيقات بإصدارات جديدة دون التأثير على تطبيقات العميل.
يمكن للمستخدمين الاستمرار في استخدام الإصدارات القديمة أو الانتقال إلى الإصدارات المتقدمة في الوقت المناسب. إذا كانت هناك تغييرات جديدة على السجلات ، فقم بتضمينها في الوثائق حتى يكون المستخدمون على دراية بذلك.
يحتوي Microsoft Graph API على سجلات تغيير موثقة جيدًا:
أخيرًا ، قم بتضمين جهات الاتصال المهمة في الوثائق للحصول على الدعم والتغذية الراجعة. يضمن ذلك إمكانية وصول المستخدمين إليك من خلال تقارير الأخطاء والمعلومات حول كيفية تحسين واجهة برمجة التطبيقات.
قيمة وثائق API
إذا قمت ببناء API للقيمة التجارية ، فإن الاستهلاك يحدد نجاحها. ولكي يستهلك المستخدمون واجهة برمجة التطبيقات الخاصة بك ، يجب أن يفهموها.
التوثيق يضفي الحيوية على واجهة برمجة التطبيقات. يشرح المكونات بالتفصيل بلغة بسيطة تبيع قيمتها واستخدامها للمستخدمين. سيستهلك المستخدمون واجهة برمجة التطبيقات (API) الخاصة بك بسعادة إذا كانت لديهم تجربة مطور رائعة.
يساعد التوثيق الجيد أيضًا في تبسيط صيانة وتوسيع نطاق واجهة برمجة التطبيقات. يمكن للفرق التي تعمل مع API استخدام الوثائق لإدارتها.