داریا بلاگ

چجوری خروجی API تمیز داشته باشیم

داشتن یه استاندارد تو ارائه API به دیگر برنامه نویسان میتونه علاوه بر حرفه ای و کامل نشون دادن کار، باعث بشه کسایی هم که دارن از این API استفاده میکنن کمترین ابهام و سوال رو داشته باشن که خود این موضوع هم باعث کمتر شدن مشکلات و افزایش سرعت توسعه پروژه میشه. تو این پست ما چند مورد از استاندارد های کلی برای ارائه API رو بررسی میکنیم. 1. اولین و مهمترین مورد؛ داکیومنت مناسب داشتن داکیومنت مناسب باعث راحت تر شدن خوندن و تست سیستم میشه و هر کسی که هم داره از سیستم استفاده میکنه میتونه خودش بره بخش های مورد نیازش رو ببینه، یکی از مهمترین ابزار های داکیومنت سازی که متن باز ( open source ) هم هست، swagger هست. که داکیومنت کاملی برای پیاده سازی داره و میتونین از سایتش بخونین. 2. پسوند فایل رو تو اسم متد نزار یه سری از برنامه نویس ها پسوند فایل رو هم تو اسم متد میارن مثلا: /users/{id}/pending-orders.json به جاش از این استفاده بهش: /users/{id}/pending-orders 3. عدم خلاصه نویسی اسم ها تا جای امکان اسم ها کامل نوشته بشه تا هر کسی که داره متد هارو میبینه کامل به عملکرد متد ها آشنا بشه 4. از اصطلاحات تخصصی استفاده نشه کسی که داره متد هارو میبینه شاید کسی هست که میخواد قالب وب سایتی رو داینامیک کنه یا اپی رو بنویسه و هیچ شناختی از اصطلاحات کاری شما نداره، که همین موضوع باعث میشه برنامه نویس API نیاز باشه مجددا متد هارو توضیح بده مثلا به جای استفاده از : /users/{id}/pan از این استفاده بشه : /users/{id}/user-number 5. از اسم جمع برای لیست استفاده بشه اگه جایی قرار یه لیستی به کاربر برگردونده بشه، بهتره از اسم جمع برای متد استفاده بشه که استفاده کننده ها هم بدونن قراره لیست بگیرن از این متد. 6. تو خروجی جیسون از camelCase استفاده کنین به جای این : { user_name: "Mehdi" } شیوه درست : { userName: "Mehdi" } 7. نسخه بندی (versioning) رو فراموش نکن فقط به الان فکر نکن، به توسعه و آینده هم فکر کن. استفاده از نسخه بندی باعث میشه هیچ کدوم از کلاینت ها چه قدیمی و چه جدید موقع ارتقا سیستم براشون مشکلی پیش نیاد. https://api.dariatech.com/v1/users با این روش وقتی که بخش کاربرا به روز رسانی داشت، هنوز هم نسخه قدیمی برای کاربران فعلی فعاله میتونن بدون مشکل استفاده کنن و هم اینکه میشه نسخه جدید رو از اپلیکیشن به کاربران عرضه کرد. 8. صفحه بندی رو فراموش نکن از صفحه بندی برای ارسال دیتا به کلاینت استفاده کنین، تا حجم زیادی از اطلاعات برای کلاینت ارسال نشه. 9. از پروتکل رمزنگاری شده استفاده کنین به جای استفاده از http از https استفاده کنین، چون علاوه بر امنیت بیشتر ، رو بعضی از کلاینت ها مثل نسخه های جدید اندروید از http برای زدن درخواست به سرور جلوگیری میشود.