همانند هر قسمتی از نرم افزار، مستندسازی بخش بسیار مهمی در پیشرفت و بهبود نرم‌افزار به حساب می آید. این زمانی اهمیت بیشتری می‌یابد که شما قصد داشته باشید رابط برنامه‌نویسی برنامه کاربردی (API) REST توسط برنامه‌نویسان شما با کمترین مشکل درک شود. در این جا به برخی روش‌ها برای این منظور اشاره خواهیم کرد.
معماری REST (Representational State Transfer)، یک معماری وب سرویس برای انتقال اطلاعات بین کلاینت و سرور است و نسبت به وب سرویس‌های پیچیده‌ای مثل SOAP مزایای بسیاری دارد و احتمالا مورد توجه شما نیز قرار گرفته است.
داشتن رابط برنامه‌نویسی REST در سیستم امکان ارتباط راحت‌تر را با سیستم شما فراهم می‌آورد و این باعث می‌شود تا سیستم شما توسط توسعه‌دهندگان بیشتری مورد استفاده قرار گیرد. هرچند، در صورتی که مستند مربوطه کامل نباشد و یا خواندن آن مشکل باشد باعث سردرگمی در هنگام استفاده از آن خواهد شد. بنابراین، مستندسازی خوب یکی از الزامات جهت استفاده از API شما توسط کاربران دیگر می‌باشد. بنابراین، چه کارهایی را می‌بایستی انجام دهیم؟
تا جای ممکن اطلاعات به درد بخور را بگنجانید.
این که کاربران بدانند با فراخوانی API شما چه اطلاعاتی به دست خواهند آورد بسیار مفید خواهد بود. برای مثال در اینجا برخی از اطلاعات کلیدی که می‌بایستی در مستند شما باشد را مرور می‌کنیم:
- عنوان: این ایده خوبی خواهد بود که عنوان مناسبی را برای فعالیتی که انجام خواهد شد انتخاب نماییم. راهنمایی با استفاده از URL احتمالا سردرگمی با در برخی موارد با درک پایین عملکرد مربوطه را در بر خواهد داشت. برای نمونه، “دریافت تمامی widgetها” یا “ارسال پیام جدید” عنوانی مناسب باشد.
- URL: مسیری که برای فراخوانی استفاده می شود. متغیرها با دو نقطه مشخص شده اند:1/widgets /widgets/:id /widgets?type=:type
- نوع درخواست: مشخص کنید که چه نوع درخواستی می‌بایستی ایجاد گردد – GET، POST، PUT و یا DELETE.
- پارامترها: تمامی پارمترهای موجود و اختیاری یا الزامی بود آنها را مشخص نمایید.
- پاسخ مورد انتظار: نوع پاسخ مورد انتظار کاربر در صورت موفقیت و یا عدم موفقیت را مشخص نمایید. برای نمونه، API در صورت موفقیت مقدار ۲۰۰ و در صورت عدم تایید کاربر مقدار ۴۰۱ را باز خواهد گرداند.
البته این‌ها مقدمات می باشند. احتمالا شما علاقه‌مند هستید تا نکاتی خاص یا مثال‌هایی را برای هر مسیر مشخص کنید که این امر باعث ترغیب توسعه‌دهندگان برای استفاده از API شما خواهد شد.
ثبات داشته باشید
علاوه بر ارائه اطلاعات درست، یکپارچگی و ثبات در ارائه اطلاعات نیز کار خوبی به نظر می‌رسد. از الگویی هماهنگ و مناسب برای نمایش مستندات هر مسیر استفاده نمایید (به خصوص استفاده از ساختاری همراه با جدول مناسب خواهد بود). همچنین از نام‌گذاری یکسانی بهره ببرید.
برای نمونه، از دو واژه برای دستیابی به یک شیء یکسان خودداری نمایید، مثلا “کاربران سیستم” را با عنوان “کاربر” و “اعضاء” مورد استفاده قرار ندهید. در صورتی که آنها موجودیت‌های متفاوتی در سیستم شما می‌باشند، از مشخص کردن تفاوت آنها به صورت واضح اطمینان حاصل نمایید که این مسئله باعث جلوگیری از سردرگمی خواهد شد.
منبع:
