Menu
97 35 94 66  info@samiaco.ir
17

ضرورت ایجاد مستندات API خوب در سایت

ضرورت ایجاد مستندات API خوب در سایت

مستندات API مرجع استفاده از سرویس های یک سایت می باشد چرا که پس از طراحی سایت برای دسترسی به سرویس های آن ها از طریق نرم افزار دیگر و یا طراحی اپلیکیشن های موبایل های هوشمند نیاز است از API های سایت استفاده کرد در واقع این API ها رابط بین اپلیکیشن ها و یا نرم افزار های دیگر با سرویس های سایت می باشند بنابراین ایجاد یک مستند خوب برای این API ها که توسعه دهندگان دیگر بتوانند از آن ها به نحوه خوبی استفاده کنند بسیار مهم می باشد . ما در این مقاله می خواهیم به برخی از این نکات بپردازیم تا بتوانیم شما را در امر مستند سازی برای API ها یاری نماییم .

مخاطبان خود را به خوبی بشناسید

برای نوشتن مستندات یک API نیاز است بدانید دقیقا با چه افرادی سرو کار دارید ، آیا افرادی که مستندات API شما را می خوانند دانش کافی در مورد انواع API ها دارند ؟ احتمالا مستندات درست شده توسط چند طیف دیده می شوند دسته اول توسعه دهندگان می باشند آن ها اصولا با انواع API ها آشنا می باشند و می دانند دقیقا چه می خواهند بنابراین این دسته اصولا مشکلی بابت پیدا کردن API های شما ندارند . دسته دوم آن های می باشند که تازه کار بوده و واقعا تجربه کافی در مورد API ندارند این دسته از افراد حتی شاید دانشی از انواع API ها ندارند بنابراین باید در ابتدا طوری مستندات را آماده کرد که اگر شخص و یا تیمی دانش کافی نداشته است ابتدا آن ها را برای آشنا کردن با API ها آماده کنیم این کار می تواند از طریق یک لینک که متنی مانند آشنای با API ها و جملاتی مانند این باشد . حتی می توان آن ها را به لینکی ویدئویی که در یوتیوب و یا آپارات آپلود شده است هدایت کرد. دسته بعدی اشخاصی هستند که نمی خواهند با جزئیات API های شما آشنا شوند ولی برای اینکه به تیم خود و یا تیم توسعه ای که قرار است با آن ها ارتباط برقرار کنند نیاز به خواندن مستندات API های شما برای قابلیت های آن دارد . بنابراین باید قسمتی از مستندات شما به صورتی باشد که امکانات API ها در آن به صورت مختصر لیست شود .


پارامترهای مشخص و نوع آن ها در مستندات API ها و مثال های واضح در مورد آن

باید دانست یکی از مهم ترین قسمت های مستندات API ها ، پارامترهای آن ها می باشند اینکه چه تعداد پارامتری با چه نوعی در کدام متد و یا تابع فرستاده می شود بسیار مهم می باشد چرا که اگر به درستی نوع و تعداد آن ها مشخص نشود نمی توان از توسعه دهندگان داخلی و خارجی انتظار داشت که به درستی API های شما را درک کنند . همچنین نوع داده ای که تابع و یا متد برگشت می دهد نیز باید کاملا شفاف باشد برخی از مستندات خوب در API ها از یک مثال برای هر یک از متدها استفاده می کنند تا شفافیت کامل را برای توسعه دهندگان روشن نمایند .

پیغام خطا

هنگامی که مشکلی در حین توسعه اتفاق می افتد حل مشکل بدون مستندات دقیق می تواند فرآیند خسته کننده و وقت گیر باشد. برای ایجاد این فرایند به صورتی که ممکن است، پیغام خطا باید به توسعه دهندگان کمک کند: مشکل چیست؟ آیا خطا از کد خود یا از استفاده از API حاصل می شود؟ .  چگونگی رفع آن مشکل : تمامی خطای های نمایش داده شده باید توسعه دهنده را دقیقا آگاه کند که چه مشکلی پیش آمده است و راه کار آن برای رفع این مشکل چیست ، برای این کار بهترین روش به این صورت می باشد که با یک مثال از خطای به وجود آمده و رفع آن توسعه دهنده را آگاه سازید .


راهنمای سریع  

یکی از بخش های که باید همیشه در مستندات باشد همین قسمت است بسیاری از توسعه دهندگان با تجربه با انواع API ها درگیر بوده اند و یا اینکه از نسخه های قبلی شما استفاده کرده اند و می دانند دقیقا چه می خواهند و فقط یک راهنمای سریع و شفاف آن ها را به مقصد خود می رساند .  

بنابراین بعد از طراحی سایت یکی از بخش های که باید سریعا برای آن مستند ایجاد کرد API ها می باشند چرا که ممکن است در نرم افزار های و یا اپلیکیشن ها از آن استفاده شود .

تعداد امتيازات: (1) Article Rating
تعداد مشاهده خبر: (96)
گروه خبر: طراحی سایت
کد خبر: 2368


  • ضرورت ایجاد مستندات API خوب در سایت