فهرست مطالب
-
مقدمه
-
API چیست؟
-
چرا مستندات خوب مهم است
-
بخش های اساسی مستندات API
-
نکات پیشرفته مستندات
-
بهترین شیوه هایی که آموخته ام
- پایان
مقدمه
از آنجا که توسعه نرم افزار تکامل یافته است ، API ها (رابط های برنامه نویسی برنامه) سیستم ها و خدمات مختلف را به هم متصل می کنند. فهمیدم که حتی قدرتمندترین API ها نیز به اسناد و مدارک روشنی نیاز دارند تا واقعاً مفید باشند. در این مقاله نحوه ایجاد مستندات Clear API به اشتراک می گذارد. در پایان این پست ، شما یک الگوی ضد گلوله برای نوشتن اسناد و مدارکی خواهید داشت که حتی هم تیمی خواب شما نیز می تواند دنبال کند.
API چیست؟
API مجموعه ای از قوانین است که به برنامه های مختلف اجازه می دهد تا ارتباط برقرار کنند. این به عنوان یک قرارداد بین ارائه دهنده داده (سرور) و مصرف کننده داده (مشتری) عمل می کند.
API ها به توسعه دهندگان کمک می کنند:
- دسترسی به ویژگی های سایر سیستم ها
- داده ها را در سیستم های خارجی بازیابی یا اصلاح کنید
- چندین سرویس را یکپارچه ادغام کنید
- بر روی سیستم عامل های موجود بدون دانستن داخلی آنها ساخته شده است
در پروژه API خبری من ، کاربران می توانند از طریق نقاط پایانی ساده و بدون نیاز به درک ساختار پایگاه داده ، اطلاعاتی در مورد کاربران ، مقالات ، نظرات و مباحث دریافت کنند.
چرا مستندات خوب مهم است
مستندات خوب راهنمای تور دوستانه شماست. هیچ کس دوست ندارد در پیچ و خم نقاط پایانی گم شود.
برای افرادی که از API شما استفاده می کنند:
- یادگیری آسان تر: توسعه دهندگان API شما را به سرعت درک می کنند
- برای اجرای سریعتر: نمونه های پاک به سرعت بخشیدن به ادغام کمک می کنند
- کمتر سوال: مستندات خوب به سوالات متداول پاسخ می دهد
- تجربه بهتر: توسعه دهندگان می توانند به جای فهمیدن API شما روی ساختمان متمرکز شوند
برای افرادی که API را ارائه می دهند:
- کاربران بیشتر: API های مستند خوب توسعه دهندگان بیشتری را به خود جلب می کنند
- ثبات: مستندات به تیم شما کمک می کند تا در همان صفحه بماند
- کار پشتیبانی کمتر: زمان کمتری به سوالات اساسی پاسخ می دهد
- طراحی بهتر: نوشتن مستندات اغلب مشکلات طراحی را نشان می دهد
بخش های اساسی مستندات API
در اینجا بخش های اصلی مستندات API خوب آورده شده است:
1. مقدمه و نمای کلی
با یک توصیف ساده از آنچه API شما انجام می دهد و چرا وجود دارد ، شروع کنید:
API documentation for the NC News API
2. URL پایه
به وضوح URL پایه را برای همه درخواست ها نشان دهید:
"base_url": "/api"
3. لیست نقاط پایانی
نقاط پایانی را در گروه های منطقی سازماندهی کنید. برای API اخبار من ، من آنها را به این صورت گروه بندی کردم:
- اطلاعات API
- کاربران
- موضوعات موضوعاتی
- مقالات
- نظرات
4. اطلاعات دقیق در نقطه پایانی
برای هر نقطه پایانی ، شامل موارد زیر است.
الف روش و مسیر HTTP
روش (دریافت ، ارسال ، قرار دادن ، پچ ، حذف) و مسیر کامل را نشان دهید.
ب. شرح
به طور خلاصه توضیح دهید که نقطه پایانی چه کاری انجام می دهد.
مثال:
"GET /api/users": {
"description": "Returns an array of users with the username, name and avatar url"
}
ج. درخواست پارامترها
تمام پارامترهای مورد نیاز در درخواست را توضیح دهید.
د. قالب پاسخ
نشان دهید که پاسخ های موفق با مثالها چگونه به نظر می رسند.
مثال:
"exampleResponse": [
{
"username": "butter_bridge",
"name": "jonny",
"avatar_url": "https://www.healthytherapies.com/wp-content/uploads/2016/06/Lime3.jpg"
}
]
ه. رسیدگی به خطا
کدهای خطای احتمالی را لیست کنید و در صورت وقوع آنها.
مثال:
"errors": [
{
"status": 404,
"msg": "User does not exist"
},
{
"status": 409,
"msg": "Username already exists"
}
]
f. درخواست ها و پاسخ های مثال
درخواست های نمونه را نشان دهید و چه پاسخی دریافت می کنند.
نکات پیشرفته مستندات
کنترل نسخه برای مستندات
با تغییر API ، اسناد را به روز کنید:
- از شماره های نسخه برای API خود استفاده کنید
- مستندات را بین نسخه ها ثبت کنید
- به کاربران کمک کنید تا هنگام وقوع تغییرات بزرگ به روز شوند
با استفاده از Markdown
برای دستیابی به Markdown از Markdown استفاده کنید:
- قالب بندی مداوم
- برجسته سازی کد
- به روزرسانی های آسان
- با کنترل نسخه خوب کار می کند
بهترین شیوه هایی که آموخته ام
از طریق تدوین پروژه API خبری من ، من اصول کلیدی را که مستندات واقعاً مفید تولید می کنند ، شناسایی کردم:
تعادل کامل با وضوح
مستندات خوب همه چیزهایی را که توسعه دهندگان باید بدانند بدون اینکه آنها را تحت الشعاع قرار دهند ، پوشش می دهد. برای API اخبار من ، من یک الگوی ثابت برای هر نقطه پایانی ایجاد کردم که شامل تمام اطلاعات ضروری (روش ، مسیر ، پارامترها ، پاسخ ها) در حالی که توضیحات را مختصر و متمرکز نگه می دارد. این رویکرد ساختار یافته به کاربران کمک می کند تا دقیقاً آنچه را که به سرعت نیاز دارند پیدا کنند.
نمایش ، فقط نگو
مستندات از طریق مثال زنده می شود. وقتی یک نقطه پایانی را توضیح می دهم GET /api/articles، من شامل:
- یک URL درخواست نمونه
- چه پارامترهایی بر نتایج تأثیر می گذارد
- یک مثال پاسخ کامل که ساختار داده را نشان می دهد
- سناریوهای خطای مشترک
این مثال های دنیای واقعی به توسعه دهندگان کمک می کند تا نحوه استفاده از API و آنچه را که انتظار دارند تجسم کنند و در طول اجرای آنها باعث صرفه جویی در وقت قابل توجهی شود.
مستندات خود را حفظ و تکامل دهید
مستنداتی که از همگام سازی با API شما خارج می شود به سرعت بی فایده یا حتی مضر می شود. من به روزرسانی های مستندات بخشی از گردش کار توسعه خود را ساخته ام – هر زمان که یک نقطه پایانی را تغییر می دهم ، یک ویژگی را اضافه می کنم یا اشکالی را برطرف می کنم که بر رفتار تأثیر می گذارد ، بلافاصله مستندات مربوطه را به روز می کنم. این تعمیر و نگهداری مداوم تضمین می کند که توسعه دهندگان همیشه اطلاعات دقیقی دارند.
علاوه بر این ، من اصطلاحات مداوم را در تمام اسناد و مدارک (با استفاده از “مقاله” نه “ارسال” در یک بخش و “داستان” در بخش دیگر) حفظ می کنم ، که از سردرگمی جلوگیری می کند و به توسعه دهندگان کمک می کند تا یک الگوی ذهنی روشنی از نحوه عملکرد API بسازند.
نکته پاداش – سریع درخواست های حلقه ای را بگیرید
با باز کردن ابزارهای توسعه دهنده ، حرکت به برگه شبکه و کلیک راست بر روی یک تماس API ، می توانید به سرعت درخواست های CURL را به API دریافت کنید ، جایی که گزینه کپی و چند گزینه را خواهید داشت:
یک پرونده changeLog را حفظ کنید:
با ردیابی هر نسخه ، تاریخ و خلاصه تغییرات در changeLog.md در ریشه repo ، مانند یک سند درجه یک مانند یک سند درجه یک رفتار کنید تا مصرف کنندگان آن را بلافاصله با استفاده از نسخه های معنایی (major.minor.patch) مشاهده کنید و آن را در changelog خود صدا کنید. این سیگنال ها در مقابل تغییرات غیرقانونی با یک نگاه ، می شکند.
پایان
مستندات خوب API حرفه ای بودن را نشان می دهد. این یک اتفاق پس از آن نیست بلکه بخش اصلی توسعه API است. پیروی از این دستورالعمل ها به شما در ایجاد مستنداتی کمک می کند که API شما را با ارزش تر و آسان تر کند.
به یاد داشته باشید: اسناد عالی فقط توضیح نمی دهد که چگونه API شما کار می کند ، بلکه به توسعه دهندگان کمک می کند تا تصور کنند که چه چیزی می توانند با آن بسازند.
