اینکه یه API بنویسی کار ساده ای هست ولی طراحی یه API با عمر بالا کار سختی هست. این کار رو با RAML میتونی ساده تر، visually و به همراه تست کردن انجام بدی. یعنی API خودتو مینویسی و به کاربرات میدی تا تست بکنن. بعدش feedback هاشون رو میگیری درحالی که یه خط کد هم نزدی!
برای طراحی API از عباراتی که همه فهم باشن استفاده میکنی و برای دیدن خروجی کار هم از API Workbench یا API Designer استفاده میکنی. تو میتونی به صورت تصویری ببینی که API چه شکلی شده، چجوری کار میکنه و چه احساسی رو داره القاء میکنه.
توی RAML میتونی design pattern ها رو با code reuse ترکیب بکنی. بجز تائید کاربرات که میگن API خوبه میتونی از مزایای library ها، overlay ها، trait ها و resourceType ها استفاده بکنی تا مطمئن بشی که API پایدار باقی میمونه و نیازی به دوباره کاری نخواهی داشت.
فکر کردن به اینکه API شما نیاز های کاربراتون رو مرتفع میکنه کافی نیست. باید مطمئن بشی. توی RAML به راحتی میای یه prototype از API خودت تهیه میکنی و پخشش میکنی بین کاربرات. در ضمن اینکه RAML با ابزار هایی مثل پستمن integrate شده.
حتی میتونی به کاربرات بگی که برن از ابزار هایی مثل API notebook استفاده بکنن. یا حتی بهت بگن که تو دنیای واقعی با API تو چطوری تعامل می‌کنن.
چونکه میتونی از کاربرات feedback بگیری و بعدش API خودت رو redesign کنی و دوباره ازش prototype درست کنی میتونی باگ ها رو قبل از اینکه توی نسخه production خودشون رو نشون بدن شناسایی و حذف بکنی.
اولین IDE با امکانات کامل برای طراحی API. این نرم افزار ویژگی هایی مثل: پشتیبانی از git، ابزار های refactoring و ... داره که کار رو خیلی ساده کرده.
یه اپلیکیشن وب که بهتون اجازه میده به صورت تیمی روی طراحی یه API کار بکنید.
با دستور `npm i -g api-designer` نصب بکنیدش. و بعدش `npm i -g request` باید بزنید. روی پورت ۳۰۰۰ بالا میاد. اگر هم میخواید روی داکر داشته باشیش میتونی بری توی داکر هاب و api-designer رو سرچ کنی.
پلاگین ها
شما میتونید از پلاگین هایی هم که ساخته میشه استفاده بکنید.
برای تولید API خودتون توی نود.جی‌اس از کتابخونه جاوااسکریپتی Osprey استفاده بکنید که یه کتابخونه قوی و قشنگ تو این حیطه هست.
برای API مهم ترین چیز اینه که backward compatibility break نداشته باشه. توی raml میتونی بعد از اینکه spec ها رو مشخص کردی بگی به صورت خودکار برای Continuous Integration تست بنویسه. ابزار های معروفی بعلاوه سرویس های معروفی مثل SmartBear ،API Science و API Fortress برای این کار هستن.
مثلا توی نود.جی‌اس ما از Abao برای تست کردن کد بک‌اندی که زدیم با داکیومنتی که به فرمت raml نوشتیم استفاده می‌کنیم.
با این پکیج به راحتی میتونی داکیومنتی که نوشتی رو به سیستم های Continuous Integration ای مثل Travis CI یا Jenkins بدی و بعدش مطمئن باشی که داکیومنتی که نوشتی همیشه با کدی که زدی میخونه. این کار رو abao با کمک پکیج mocha انجام میده.
نکته خوب دیگه در مورد RAML اینه که میتونی توی postman ایمپورت بکنیش و ازش تست بگیری.
داکیومنت نوشتن توی raml علاوه بر ساده شدن Sync هم شده. با کمک ابزار هایی مثل API Console ،API notebook و RAML 2 HTML داکیومنت ها on the fly به سرعت تولید میشن.
با کمک این ابزار میتونید به صورت live با داکیومنت API تعامل داشته باشی و علاوه بر اون کاربرات هم می‌تونن API رو به صورت real time تست بکنن. اگه مثل من خوره داکر هستی اینجا ایمیجش هم هست. این ابزار رو با نود.جی‌اس نوشتن.
این ابزار میاد برات یه صفحه html ای متناسب با فایل RAML ای که بهش دادی بهت میده. این ابزار رو هم با نود.جی‌اس نوشتن و میتونی توی کامند لاین هم ازش استفاده بکنی. برای ایمیج داکر هم این رو بزنید.
docker pull mattjtodd/raml2html:7.6.0
برای تولید SDK میتونید از سرویس دهنده هایی مثل apimatic یا restunited استفاده بکنید.
این سرویس یه تغییر بزرگ تو استفاده از API ها بوجود آورد. بهشون اجازه داد به سادگی از API استفاده بکنن، دیتا رو تغییر بدن، به API های مختلفی وصل بشن و با استفاده از markdown به راحتی میتونی Use case های مختلف API خودت رو شرح بدی.
میخوای بیشتر بدونی به این لینک، این و این یه سر بزن. اگه دقت کرده باشی فهمیدی که API notebook همه حدس های ممکنه رو که یه دولوپر ممکنه چجوری با API تو (مخصوصا بخش های مهمش) کار بکنه میزنه.
چیزی که API notebook رو منحصر به فرد میکنه اینه که هر کسی میتونه notebook خودش رو بسازه یا اونی که هست رو clone بکنه و بعد توش بیاد use case خاص خودش رو بنویسه و با اشتراک گذاری اون نیاز خودش رو به راحتی به همه بگه.
این یعنی به راحتی میشه مشخص کرد که ایراد تو کدای شما هست یا توی کد اونا. شما در همون لحظه میتونید چک کنید که ایراد از نوع فراخوانی API هست یا اینکه API شما ایراد دارد.
