بنابراین ، شما یک API فوق العاده ایجاد کرده اید ، اما اگر مستندات شما به عنوان یک مدیریت مالیاتی خوانده شود ، حتی خنده دار ترین توسعه دهندگان نیز فرار می کنند. یا بدترین ، ناقص است یا اشتباهاتی وجود دارد … اوه!
مستندات واضح و کوتاه API سنگ بنای تجربه موفقیت آمیز توسعه دهندگان است و بیانگر بینش فنی تجارت شما است. داشتن درخواست های خوب و مستند به کاربران شما اجازه می دهد تا با یکپارچه سازی با API خود ادغام شوند و باعث صرفه جویی در وقت و ناتوانی در آنها شوند. در اینجا ، در Ayrshare ، ما اهمیت ارتباطات مؤثر را درک می کنیم و این شامل تولید اسناد API توسعه دهندگان ستاره است. به عنوان مثال ، مستندات API اجتماعی ما را ببینید.
در این مقاله ما خودمان را در 5 نکته اصلی غوطه ور خواهیم کرد تا اطمینان حاصل کنیم که مستندات درخواست API شما در درجه اول است:
1. یک بررسی API ارائه دهید
با ارائه یک بررسی واضح از API خود ، کارها را شروع کنید. این شامل:
- هدف و ویژگی های اصلی API خود را توضیح دهید. توضیح اینکه چرا این API وجود دارد می تواند بهترین صفحه فروش شما باشد.
- نقاط پایانی اصلی و کارکردهای آنها را تشریح کنید. محتوا را وارد کنید تا خوانندگان شما بتوانند به سرعت دسترسی به نقطه پایان را اسکن کنند.
- شامل هر اصول معماری یا طراحی است. شما می توانید فلسفه خود را در اینجا توضیح دهید.
- نحوه عملکرد احراز هویت را شرح دهید. چگونه کاربران شما می توانند به API ، به عنوان مثال ، کلیدهای API ، OAUTH و نحوه دستیابی به داده های شناسایی دسترسی پیدا کنند.
2. نام ها و توضیحات نقاط پایانی را روشن کنید
برای توضیحات کوتاه تلاش کنید که به راحتی عملکرد درخواست را توضیح می دهد. بیش از حد از زبان فنی خودداری کنید و درک کاربران را در اولویت قرار دهید. به عنوان مثال ، درخواست Ayrshare “Get Profile Profile” به طور خلاصه هدف خود را منتقل می کند ، یعنی دریافت کلیه پروفایل های مربوط به مشخصات اصلی.
روش HTTP و نقطه پایانی
نشان دادن نقطه پایانی واقعی به نام روش HTTP مورد استفاده بسیار مهم است.
در این مثال ، ما در HTTP سبز روش پست و URL نقطه پایان را مشخص می کنیم.
برای درخواست های ارسال و ارسال ، درخواست درخواست بدن را به طور کامل ثبت کنید. نام ویژگی ها ، انواع داده ها (رشته ، بلوار) و هدف آنها را در درخواست تشریح کنید. مقادیر قابل قبول را برای خواص با محدودیت ها نشان دهید. به عنوان مثال ، درخواست “ایجاد یک پروفایل کاربر” Ayrshare روشن می کند که خاصیت “عنوان” یک رشته اجباری است ، در حالی که DisableCocial مجموعه ای از مقادیر اختیاری است که در آن مستندات همه شبکه های اجتماعی موجود را لیست می کند.
ناوبری API می تواند برای کاربران نهایی دشوار باشد ، بنابراین از چند نمونه با مثال نترسید.
توصیه می کنیم:
- با استفاده از یک کنوانسیون نامگذاری ، یک عمل گرا. ما عاشق روش HTTP هستیم که فعل عمل نقطه پایانی باشد. به عنوان مثال ، A /Post یا Get /Analytics را منتشر کنید.
- با استفاده از روشهای HTTP به درستی ، مانند درک تفاوت بین یک پچ و یک قرار دادن.
هشدارها و محدودیتهای سرعت را اعلام می کند
هشدارهای مهم
از عناوینی مانند “مهم” یا “هشدار” یا نمادهای معادل استفاده کنید تا توجه به جزئیات تعیین کننده در اسناد را جلب کنید. این تضمین می کند که کاربران اطلاعات مهم را از دست ندهند. به عنوان نمونه ، درخواست های “Update User” Ayrshare: “Google برخی از زمینه های موقعیت مکانی Google Business را محدود می کند تا 5 بار در یک دوره 24 ساعته موبایل به روز شود.”
محدودیت سرعت API
هر API محدودیت سرعت دارد یا باید داشته باشد. این محدودیت ها ثبات سیستم را تضمین می کند و در برابر بازیگران یا بدون خودرو محافظت می کند. به عنوان مثال ، شما به ندرت می خواهید به کاربر اجازه دهید با همان API تماس بگیرید 100k بار در دقیقه – زیرا معمولاً یک اشتباه است. این تعداد تماس ها می توانند سیستم شما را بارگیری کنند یا هزینه های قابل توجهی را برای شما و کاربر داشته باشند.
فرض کنید که شما محدودیت های سرعت را تعیین کرده اید و پاسخ های مربوطه 429 HTTP را برگردانید ، باید با جزئیات محدودیت سرعت را شرح دهید. همچنین ، حتماً انتظارات را برای محدود کردن سرعت API به شرایط خود ، مانند یک سیاست استفاده منصفانه اضافه کنید.
3. نمونه های مفصلی از درخواست و پاسخ
درخواست های API
عالی ، من مشخصات API را می دانم ، اما چگونه می توانم از آن استفاده کنم؟ نمونه هایی از کد! و نه فقط یک زبان برنامه نویسی بلکه به همان اندازه که می توانید پشتیبانی کنید. به عنوان مثال ، Ayrshare پنج نمونه زبانی مانند Curl ، Node.js ، Python ، PHP و C#را ارائه می دهد.
این نمونه از تماس های API باید تماس های اصلی را نشان دهد تا کاربر بتواند شروع کند. از اضافه کردن هر پارامتر خودداری کنید زیرا هم برای اولین بار برای کاربران گیج کننده و هم دشوارتر است. این نمونه های پیچیده تر از سایر بخش های اسناد را ذخیره کنید. و اگر واقعاً می خواهید کاربران خود را تأمین کنید ، با تمام درخواست های نقطه پایانی یک فایل postmanv تهیه کنید. کاربران ما عاشق پرونده JSON Postman هستند تا به سرعت شروع شوند.
اگر برخی از زبانها مانند جاوا یا روبی را از دست بدهید ، چه می کنید؟ ما معمولاً توصیه می کنیم کاربران ما از قدرت هوش مصنوعی مانند ChatGPT یا Claude AI استفاده کنند. هر دوی آنها یک کار ترجمه خارق العاده از یک زبان به زبان دیگر انجام می دهند. Postman همچنین دارای کدهای خودکار فوق العاده است.
API پاسخ داد
نمونه های پاسخ به عنوان پانل شروع برای تعامل موفقیت آمیز API عمل می کنند. حداقل یک نمونه از یک پاسخ موفق (2xx) ، همراه با پاسخ های خطا (به عنوان مثال کدهای 4xx یا 5xx) را برای کمک به عیب یابی درج کنید. به عنوان مثال ، مستندات Ayrshare پاسخ مثالی به اظهار نظر در مورد این نظر ارائه می دهد ، نشان می دهد که کاربران ساختار داده می توانند انتظار داشته باشند که با موفقیت ایجاد شوند ، و همچنین آنچه را که در دو مورد مختلف از خطاها انتظار دارند.
این نمونه های پاسخ همچنین گزینه های شما را نشان می دهد. به عنوان نمونه ، API ما برای تجزیه و تحلیل های اجتماعی API بینش زیادی را فراهم می کند و اغلب کاربر آینده که تحقیق می کند از عرض داده های موجود تحت تأثیر قرار می گیرد.
سرانجام ، حتماً هرگونه بازگشت داده ها را توضیح دهید که کاملاً واضح نیست – ما نظرات را به نمونه های پاسخ JSON اضافه می کنیم. هرچه اطلاعات بیشتری ارائه دهید ، کاربران خود را آسان تر می کنید.
4. راهنما و درس ها را ارائه دهید
دروس و کتابچه راهنمای نوشتاری برای توسعه دهندگان که سعی در اجرای API شما دارند بسیار ارزشمند است. و آیا می دانید چه چیزی حتی بهتر است؟ درس ویدیویی! حتماً این فیلم های YouTube را برای دامنه اضافی SEO ارسال کنید.
- یک راهنمای “شروع سریع” را درج کنید. بیشتر مردم از اینجا شروع می کنند.
- برای رایج ترین موارد استفاده درس و راهنما ایجاد کنید. هنگامی که کاربران شما یک API حلق آویز با موارد کاربر کمتری دریافت می کنند ، آنها فقط قادر به اجرای نمونه های نقطه پایان خواهند بود.
- قطعات کد و SDK را به زبانهای محبوب ارائه دهید. قطعات کد را می توان در کتاب آشپزی API جمع آوری کرد. در اینجا SDK ما ارائه می دهیم ، و آنها برای توسعه دهندگان بسیار محبوب هستند ، اگرچه برخی از تماس های API را به سادگی بسته بندی می کنند.
5. اطلاع رسانی به توسعه دهندگان از تغییرات
استهلاک
هنگام بازنشستگی یک کادر درخواست یا داده ، آن را به وضوح به عنوان “پس گرفته شده” در اسناد علامت گذاری کنید. در نظر بگیرید که برای انتقال صاف به همکار به روز شده خود ارتباطی ارائه دهید. به عنوان مثال ، Ayrshare زمینه Shareurl را برای تاریخ Tiktok پس گرفت. مستندات به وضوح این را نشان می دهد و جزئیات مربوط به استفاده از قسمت Posturl را ارائه می دهد.
چه بخش جدیدی
و فراموش نکنید که بخش “آنچه جدید است” را ایجاد کنید ، که در آن شما بر تمام ویژگی های جدید جدیدی که راه اندازی کرده اید تأکید می کنید. این یک فرصت عالی برای افتخار از تمام پیشنهادات جدید است و توسعه دهندگان به این بخش گرایش می یابند تا بررسی کنند که API شما هنوز فعال است.
در اینجا Ayrshare What New New ، که شامل یک پادکست ماهانه است که به همه ویژگی های جدید نیز نگاه می کند.
ما می دانیم که داشتن اسناد عالی یکی از سنگ بنای موفقیت مشتریان است. با توجه به این نکات مربوط به اسناد API ، می توانید مستندات API را ایجاد کنید که نه تنها به عنوان یک راهنما عمل می کند ، بلکه به طور فعال از توسعه دهندگان هنگام استفاده از API خود نیز پشتیبانی و هدایت می کند. به یاد داشته باشید که مستندات عالی یک فرآیند در حال انجام است – بر اساس نیاز و بازخورد کاربران ، به اصلاح و پیشرفت ادامه دهید.
