اشتباهات رایج طراحی API و نحوه اجتناب از آنها

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

در این مقاله، ما چند استاندارد طراحی RESTful API را مورد بحث قرار می‌دهیم که می‌توانید در پروژه‌های خود برای ایجاد یک اکوسیستم API ایده‌آل اعمال کنید.

تمرکز بر منابع

هدف اساسی API ها فراهم کردن دسترسی به منابع خاص است. یک منبع API نشان دهنده بخشی از داده یا عملکردی است که API دسترسی به آن را فراهم می کند.

به عنوان مثال، در یک برنامه CRM (مدیریت ارتباط با مشتری)، منابع معمولی عبارتند از:

• مخاطبین
• منجر می شود
• حساب ها
• وظایف

یک منبع می تواند به شکل یک تک (یک حساب کاربری) یا یک مجموعه (گروهی از وظایف) باشد.

ما می توانیم یک API در قالب طراحی کنیم GET /contacts برای واکشی لیستی از تمام مخاطبین یا PUT /tasks/301 برای به روز رسانی جزئیات یک کار

نامگذاری صحیح URL

قراردادهای نامگذاری برای URL ها مهم هستند. بهتر است از اسامی برای URL های RESTful استفاده کنید، زیرا API های RESTful برای جمع آوری منابع و ارتباطات طراحی شده اند، نه برای انجام اقدامات یا عملیات.

رویکرد توصیه شده

GET /contacts

GET /tasks/:id

رویکرد کمتر ترجیحی

GET /get-contacts

GET /get-task-by-id/:id

از پارامترهای مسیر استفاده کنید

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

GET /tasks/:id

از این کار اجتناب کنید

GET /tasks

{
 id:1
}

سلسله مراتب API را حفظ کنید

حفظ سلسله مراتب منابع به خوبی تعریف شده به تعریف روابط بین منابع مختلف در یک API کمک می کند.

در مورد CRM
GET /user/{userId}/task/{taskId}

در اینجا، API به وضوح وظیفه را بر اساس شناسه وظیفه تحت یک کاربر خاص واکشی می کند.

نسخه API

APIها با رشد محصول اصلاح می شوند. بنابراین، تغییرات در API نباید روی کاربران مسن‌تر، کلاینت‌های قدیمی‌تر یا کد ظاهری تأثیر بگذارد. این زمانی است که نسخه سازی وارد می شود.

استفاده از نسخه API زمانی که:

• تغییر نام یا تغییر هر نقطه پایانی یا ویژگی
• پارامتر تغییر می کند
• تغییر فرمت داده

نسخه‌سازی را می‌توان با استفاده از تغییر مسیر URL یا با استفاده از سربرگ انجام داد.

مسیر URL
نسخه در خود مسیر تعریف شده است.
مثال: https://example.com/api/v2/user

نسخه هدر
نسخه تعریف شده در هدر API
پذیرش: نسخه = 1.0

حفظ و طراحی API ها یک چالش بی پایان است. برای محصولات مختلف، موارد استفاده و زمینه‌ها متفاوت است. این مقاله چند جنبه را پوشش می دهد که به شما در ایجاد اکوسیستم های API بهتر کمک می کند.

تیم من و من در حال توسعه LiveAPI، یک ابزار بسیار راحت برای تولید اسناد API هستیم. با استفاده از LiveAPI، می توانید اسناد API را برای هر پروژه وب در عرض چند دقیقه، با حداقل تلاش ایجاد کنید.
همچنین، پس از اتصال، LiveAPI اسناد API شما را بر اساس تغییرات کد به‌روز نگه می‌دارد.

LiveAPI را امتحان کنید و بازخورد ارزشمند خود را به اشتراک بگذارید. برای نکات و مقالات فنی بیشتر در ارتباط باشید.