9 نکته کاربردی برای طراحی API های حرفه‌ای

اگر در حال توسعه بک اند هستید، طراحی API یکی از حیاتی‌ترین مراحل کار شماست اما در بسیاری از مواقع هنگام طراحی API برای پروژه، توسعه دهندگان اهمیت زیادی به تمیز بودن ساختار طراحی، مفهومی بودن و مقیاس پذیری آن نمی دهند؛ بنابراین در طولانی مدت و با بزرگ تر شدن پروژه این موضوع باعث به وجود آمدن مشکلاتی می شود.
فرض کنید زمان آن رسیده است که API های نوشته شده را برای کاربران به اشتراک بگذارید تا از آن ها استفاده کنند. چطور می توانید مطمئن باشید که آن ها دقیقا همان چیزی که مد نظر شماست را مشاهده می کنند؟ این مساله نه تنها برای کاربران بلکه برای توسعه دهندگانی که قصد توسعه API های نوشته شده توسط شما را دارند صدق می کند. بنابراین ضروری است که در ابتدای ساخت API ها الگوی طراحی مناسبی برای این کار انتخاب شود تا تمامی افراد (کاربران و توسعه دهندگان) از آن پیروی کنند.
در این مقاله به بررسی ۹ نکته کاربردی برای توسعه هرچه بهتر این API ها می پردازیم و اصول حرفه‌ای برای طراحی API را آموزش می‌دهیم؛ از نحوه ساخت مسیرها (Endpoints) و انتخاب صحیح HTTP Methods تا وضعیت‌کدها، مدیریت خطا، کشینگ (Caching) و مستندسازی استاندارد به همراه مثال‌های واقعی برای کمک به پیاده‌سازی سریع و اصولی.

1. استفاده صحیح از متدهای HTTP در طراحی API

REST API ما را تشویق می کند تا از متدهای HTTP برای ساخت هر کدام از عملیات های مربوط به CRUD استفاده کنیم. در میان این متدها، مواردی مانند GET، POST، PUT، PATCH، DELETE معنای خاصی به endpoint های ما می دهد و به طور مثال مشخص می کند که این endpoint مربوط به ساخت (ایجاد) یک موجودیت جدید است یا حذف یک موجودیت از پیش ساخته شده:

• GET برای خواندن
• POST برای ایجاد
• PUT/PATCH برای به‌روزرسانی
• DELETE برای حذف

 همچنین با استفاده از این متدها دیگر نیازی به مشخص کردن عملیات در هنگام تعریف نام برای endpoint ها نیست. مثال زیر گویای مزایای استفاده از این متدهاست:

- GET /get_cats
- POST /insert_cats
- PUT /modify_cats
- DELETE /delete_cats
+ GET /cats
+ POST /cats
+ PUT /cats
+ DELETE /cats

2. استفاده از کدهای status مربوط به HTTP بر اساس نتیجه درخواست ارسالی

یکی از مهم ترین موارد در طراحی API ها استفاده درست از status code (کدهای وضعیت) بر اساس نتیجه ی درخواست ارسالی است. این بدان معنی است که هنگامی که عملیات موفقیت آمیز بوده یا با خطا روبرو شود می توان با استفاده از status code ها این مفهوم را به کاربر منتقل کرد.

👈 برای مطالعه بیشتر در مورد کدهای وضعیت به بخش آشنایی با کدهای وضعیت در پروتکل HTTP از دوره آموزش RESTful API در سایت سکان آکادمی مراجعه کنید.

برای مثال اگر ما 200 را به عنوان status code دریافت کنیم، می توان فهمید که نتیجه ی عملیات درخواستی موفقیت آمیز بوده است و اگر 400 را دریافت کنیم، عملیات مورد نظر با خطا روبرو شده است.
بنابراین مهم است که با status code های مختلف آشنایی داشته و از هرکدام در زمان مناسب با توجه به نتیجه ی عملیات استفاده شود چرا که در غیر این صورت باعث سردرگمی کاربران و توسعه دهندگان و در برخی موارد باعث استفاده نادرست از آن می شود. به طور مثال نمونه استفاده ی درست و نادرست از status code در زیر آورده شده است:

// Bad, we return status code 200 (Success)
// associated with an error object
{
    "status": 200,
   "error": {...}
}
// Good
{
    "status": 200,
    "data": [...]
}

3. پشتیبانی از filter، sort و pagination

در بسیاری از مواقع نیاز است تا تعداد اطلاعات دریافتی از API محدود شود. این محدودیت می تواند به دلایلی مانند بهبود سرعت انجام عملیات ها، کاهش تعداد اطلاعات دریافتی، جستجوی دریافت اطلاعات خاص و ... باشد. 
افزودن filter، sort و pagination علاوه بر دستیابی به کاربرد خاص خودشان، می تواند باعث کاهش فشار بر روی سرور شود.
به طور مثال فرض کنید در پایگاه داده، میلیون ها داده داریم، حال اگر کاربر تمام این اطلاعات را یک جا درخواست کند به یقین سرور فشار زیادی را متحمل می شود! اما با استفاده از ساختارهای sort و filter و pagination این مشکل مرتفع خواهد شد. به طور مثال می توان به صورت زیر از این عملیات ها استفاده کرد:

- GET /cats?page=2
- GET /cats?page=3&per_page=20
- GET /cats?page=2&sort=desc

4. نام گذاری endpoint ها به صورت جمعی

از آنجایی که معمولا resource ها دارای یک داده نیستند و بیشتر مواقع آن ها به صورت جمعی هستند بهتر است از نام جمعی برای endpoint ها استفاده شود.

- GET /cat
- GET /cat/:id
+ GET /cats
+ GET /cats/:id

5. نام گذاری endpoint ها بر اساس resource

اگر یک route پروژه عملیاتی را روی resource خاصی انجام می دهد، باید نام endpoint مربوط به آن با نام resource مورد نظر یکی باشد. این مسئله باعث ثبات و منظم بودن پروژه خواهد شد. بنابراین هنگامی که یک کاربر یا توسعه دهنده از API های ما استفاده کند متوجه کاربرد هر یک از route ها خواهد شد. به طور مثال اگر یک route قرار است عملیات مربوط به موجودیت Cat را انجام دهد نباید به صورت /dogs تعریف شود.

6. استفاده از route های سلسله مراتبی

فرض کنید بین موجودیت های مختلف در پروژه رابطه وجود دارد. به طور مثال اگر بخواهیم لیست موجودیت های (مثلا posts) مربوط به یک موجودیت دیگر (مثلا user) را دریافت کنیم دو گزینه پیش رو خواهیم داشت. یکی استفاده از ساختار سلسله مراتبی و دیگری استفاده از query string:

GET /users/alireza/posts/post-about-api-design
GET /posts?user=alireza&name=post-about-api-design

این روش ها در پروژه های مختلفی استفاده می شوند و استفاده از هر دو روش صحیح است. روش اول باعث استفاده بهتر از ساختار route ها می شود اما در زمانی که تعداد روابط زیاد باشد روش اول باعث طولانی شدن نام مسیرها شده و روش دوم عملکرد بهتری خواهد داشت. این بستگی به ساختار پروژه شما دارد که از کدام روش بهتر است استفاده کنید.

7. نسخه گذاری API ها

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

// URI versioning v[x] syntax
GET /v1/cats
GET /v2/dogs
GET /v3/birds

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

8. استفاده از سیستم caching

یکی از ویژگی های مثبت هر API، سرعت پاسخ دهی بالای آن است. برای دست یابی به آن در هنگام طراحی API ، می توان از caching (کشینگ) استفاده کرد. این کار نه تنها باعث افزایش سرعت پاسخ دهی API می شود، بلکه فشار روی سرور را نیز کاهش می دهد. چرا که با این کار نیاز به دست یابی به دیتابیس برای دریافت داده های تکراری کمتر خواهد شد. سرویس های بسیاری برای این کار وجود دارد که یکی از محبوب ترین آن ها Redis است.
این کار ممکن است باعث افزایش هزینه نگه داری API ها شود اما این مسئله یک نقص نیست! چرا که هزینه ی دست یابی به اطلاعات دیتابیس ممکن است در مواردی بیشتر از هزینه Cache باشد. از طرفی می توان با کم کردن زمان caching این مسئله را بهبود داد.

9. مستندسازی در طراحی API

یکی از بهترین سلاح ها و در کنار آن منفورترین کارها! در بین توسعه دهندگان مستندسازی است. در این میان مستندسازی API مستثنا نیست و یکی از ضروریات در طراحی API، مستندسازی آن است. با مستندسازی کاربران این امکان را خواهند داشت تا درباره ی API اطلاعاتی را به دست آورند که این اطلاعات شامل نوع دسترسی به آن (accessibility)، نوع درخواست و اطلاعات آن (request)، نوع پاسخ و اطلاعات آن(response)، مثال ها و ... باشد.
• دسترسی: یکی از مهم ترین ویژگی های مستند نحوه دسترسی به آن است. بهترین روش برای مستندسازی، ساخت یک مستند و ارائه آن بر روی اینترنت است. با این روش تمام کاربران قادر به مشاهده مستندها خواهند بود.
• درخواست و پاسخ: اطلاعاتی که در این قسمت قرار می گیرد باید نوع و اطلاعات موجود در درخواست و پاسخ را مشخص کند.
• مثال ها: اگر برای کاربران مثال هایی برای استفاده از هر یک از API ها آورده شود بسیار مفید خواهد بود.

Swagger و Postman دو ابزار بسیار کاربردی و مفید برای مستندسازی API ها هستند.

👈 برای آشنایی بیشتر با چگونگی مستندسازی نرم افزار، مراحل و انواع ابزارهای آن؛ به مقاله‌ای با همین نام در سکان آکادمی مراجعه کنید.

نتیجه گیری

در نظر داشته باشید که API طراحی شده، راه ارتباطی کاربران با سرویس ساخته شده توسط backend (بک اند) است. در این صورت باید دقت کرد که در طراحی آن بهترین اصول را رعایت کنیم تا کاربران به راحتی بتوانند از آن استفاده کنند. حتی اگر در حال توسعه یک پروژه شخصی هستید پیشنهاد می شود که این اصول طراحی API را در پروژه خود نیز به کار ببرید؛ چرا که هزینه ی نگه داری و توسعه ی آن در آینده کاهش پیدا می کند. همچنین این کار باعث تمرین بیشتر شما برای مشارکت در پروژه های بزرگ تر خواهد شد.

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

👈 برای مطالعه بیشتر به بخشی با عنوان ویژگی‌های یک API با طراحی مناسب از دوره ۹۷ چیزی که هر برنامه‌نویسی باید بداند مراجعه کنید.