طراحی RESTful API — راهنمای کاربردی

ما به عنوان توسعه‌دهندگان نرم‌افزار به صورت روزمره از REST API استفاده کرده یا آن‌ها را می‌سازیم. API-ها اینک به روش پیش‌فرض ارتباط بین سیستم‌ها تبدیل شده‌اند. آمازون بهترین مثال برای این نکته است که API-ها تا چه حد می‌توانند به صورت مؤثری به منظور ارتباط مورد استفاده قرار گیرند. در این مقاله قصد داریم در مورد چگونگی طراحی RESTful API به صورت بهینه برای جلوگیری از بروز اشتباه صحبت کنیم.

فرمان جف بزوس

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

1. همه تیم‌ها از این پس داده‌ها و کارکردهایشان را از طریق اینترفیس‌های سرویس ارائه می‌کنند.
2. تیم‌ها باید با همدیگر از طریق این اینترفیس‌ها ارتباط برقرار کنند.
3. هیچ نوع دیگری از ارتباط درون‌فرایندی دیگر مجاز نیست، لینک کردن مستقیم، خواندن مستقیم داده‌گاه‌های یکدیگر، مدل اشتراک حافظه و یا هر نوع درِ پشتی مجاز نخواهد بود. تنها روش ارتباطی مجاز از طریق فراخوانی اینترفیس‌های سرویس روی شبکه است.
4. مهم نیست که از چه فناوری استفاده می‌کنید، HTTP ،Corba ،Pubsub یا هر نوع پروتکل سفارشی که استفاده می‌کنید برای بزوس مهم نیست.
5. همه اینترفیس‌های سرویس بدون استثنا باید از اول طوری بازطراحی شوند که قابلیت اکسترنال شدن داشته باشند. این بدان معنی است که تیم باید طرح و برنامه‌ای داشته باشد که بتواند اینترفیس را به توسعه‌دهندگان دنیای بیرون عرضه کند. هیچ استثنایی وجود ندارد.
6. هر کس که این کار را نکند اخراج خواهد شد.

در نهایت مشخص شد که این کلید موفقیت آمازون بوده است. آمازون توانست سیستم‌های مقیاس‌پذیر بسازد و در ادامه توانست این سیستم‌ها را به صورت سرویس‌هایی مانند Amazon Web Services عرضه بکند.

مفاهیم طراحی RESTful API

در این بخش با مفاهیمی که باید در زمان طراحی RESTful API پیروی کنید آشنا می‌شویم.

فیلم آموزش ساخت REST API با دات نت – رست ای پی آی با NET 6. در فرادرس

کلیک کنید

ساده طراحی کنید

ما باید مطمئن شویم که URL مبنای API ساده است، برای نمونه اگر می‌خواهد API-هایی برای محصولات طراحی کنید باید چیزی مانند زیر باشد:

/products
/products/12345

API اول همه محصولات و API دوم یک محصول خاص را دریافت می‌کند.

از اسم (و نه فعل) استفاده کنید

توسعه‌دهندگان زیادی هستند که این اشتباه را مرتکب می‌شوند. آن‌ها عموماً فراموش می‌کنند که ما متدهای HTTP داریم که API-ها را بهتر توصیف می‌کنند و بنابراین در URL-های API-ها از فعل استفاده می‌کنند. برای نمونه API دریافت محصولات باید به صورت زیر باشد:

/products

و نباید به صورت زیر باشد:

/getAllProducts

این‌ها برخی الگوهای URL رایج هستند که تاکنون مشاهده کرده‌ایم.

از متدهای HTTP مناسب استفاده کنید

API-های RESTful متدهای مختلفی دارند که نوع عملیاتی که می‌خواهیم با آن API اجرا کنیم را نمایش می‌دهند.

• GET – برای دریافت یک منبع یا مجموعه‌ای از منابع.
• POST – برای ایجاد منبع یا مجموعه‌ای از منابع.
• PUT/PATCH – برای به‌روزرسانی منبع یا مجموعه منابع موجود.
• DELETE – برای حذف منابع یا مجموعه منابع موجود.

ما باید مطمئن شویم که متد HTTP مناسب را برای هر عملیاتی مورد استفاده قرار می‌دهیم.

از حالت جمع استفاده کنید

این موضوع کمی بحث‌انگیز است. برخی افراد دوست دارند که URL منبع دارای اسامی جمع باشد و برخی دیگر دوست دارند مفرد باشد. برای نمونه:

/products
/product

ما توصیه می‌کنیم از حالت جمع استفاده کنید، زیرا به سردرگمی در مورد این که می‌خواهیم یک منبع مفرد یا جمعی از منبع‌ها را دریافت کنیم خاتمه می‌بخشد. همچنین از افزودن موارد اضافی مانند الصاق all به URL مبنا به صورت زیر خودداری کنید:

/product/all

شاید برخی افراد از این موضوع خوششان نیابد، اما پیشنهاد ما این است که این وضعیت را در سراسر پروژه به صورت یکنواخت حفظ کنید.

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

برخی اوقات باید یک API داشته باشیم که چیزی بیش از id را به ما نشان دهد. در این موارد می‌توانیم از پارامترهای کوئری برای طراحی API استفاده کنیم.

• 'products?name=’ABC/ به getProductsByName/ ترجیح دارد.
• 'products?type=’xyz/ به getProductsByType/ ترجیح دارد.

بدین ترتیب از پدید آمدن URL-های طولانی اجتناب کرده و طراحی را ساده حفظ می‌کنیم.

از کدهای HTTP مناسب استفاده کنید

کدهای HTTP بسیار زیادی وجود دارند، ولی اغلب توسعه‌دهندگان در نهایت از دو کد 200 و 500 استفاده می‌کنند. این قطعاً رویه خوبی نیست. در ادامه برخی کدهای HTTP ارائه شده‌اند.

• 200 OK – این رایج‌ترین کد مورد استفاده HTTP است که نشان می‌دهد عملیات با موفقیت اجرا شده است.
• 201 CREATED – این کد می‌تواند زمانی استفاده شود که متد POST باید یک منبع جدید ایجاد کند.
• 202 ACCEPTED – این کد برای اعلام این موضوع استفاده می‌شود که درخواستی به سرور ارسال شده است.
• 400 BAD REQUEST – این کد زمانی استفاده می‌شود که اعتبارسنجی ورودی سمت کلاینت ناموفق باشد.
• 401 UNAUTHORIZED / 403 FORBIDDEN – این کد در صورتی استفاده می‌شود که کاربر یا سیستم مجاز به اجرای عملیات خاصی نباشد.
• 404 NOT FOUND – این کد در زمانی استفاده می‌شد که به دنبال منبع خاصی می‌گردیم و روی سیستم موجود نیست.
• 500 INTERNAL SERVER ERROR – این کد هرگز به صورت صریح صادر نمی‌شود، بلکه ممکن است در صورت بروز خطای سیستمی صادر شود.
• 502 BAD GATEWAY – این کد زمانی استفاده می‌شود که سرور یک پاسخ نامعتبر از سرور بالادستی خود دریافت کرده باشد.

نسخه‌بندی

نسخه‌بندی API-ها بسیار مهم است. شرکت‌های مختلف زیادی از نسخه‌ها به روش‌های متفاوت استفاده می‌کنند. برخی از نسخه‌بندی به صورت تاریخ استفاده می‌کنند و برخی دیگر از نسخه‌هایی به صورت پارامتر کوئری بهره می‌گیرند. به صورت معمول بهتر است نسخه را به صورت پیشوند برای منبع حفظ کنیم. به مثال زیر توجه کنید:

/v1/products

/v2/products

همچنین باید از استفاده از روش زیر خودداری کنیم:

/v1.2/products

روش فوق به این معنی است که API می‌تواند به طور مکرر تغییر یابد. همچنین نقطه ممکن است در URL-ها به سادگی دیده نشود. بنابراین آن را ساده حفظ کنید. همچنین رویه مناسب این است که همواره سازگاری رو به عقب داشته باشیم. به این ترتیب اگر نسخه API عوض شود، مصرف‌کنندگان فرصتی برای ارتقا به نسخه بعدی خواهند داشت.

از صفحه‌بندی استفاده کنید

استفاده از «صفحه‌بندی» (pagination) در مواردی که یک API ممکن است داده‌های زیادی بازگشت دهد یک ضرورت است و اگر متعادل‌سازی بار به درستی اجرا نشود، ممکن است مصرف‌کننده سرویس، آن را از کار بیندازد. همواره باید به خاطر داشته باشید که طراحی API باید با در نظر گرفتن همه سناریوهای ممکن صورت بگیرد.

در چنین مواردی استفاده از limit و offset توصیه می‌شود. برای نمونه می‌توانید به صورت زیر عمل کنید:

/products?limit=25&offset=50

این کار موجب می‌شود که یک محدودیت و آفست پیش‌فرض نیز داشته باشید.

فرمت‌های پشتیبانی شده

انتخاب روش پاسخ‌دهی API نیز حائز اهمیت است. اغلب اپلیکیشن‌های مدرن پاسخ‌های JSON بازگشت می‌دهند، مگر این که اپلیکیشنی قدیمی داشته باشید که همچنان به پاسخ XML نیاز داشته باشد.

از پیام‌های خطای مناسب استفاده کنید

همواره خوب است که مجموعه پیام‌های خطایی داشته باشید که اپلیکیشن با id مناسب ارسال و دریافت می‌کند. برای نمونه اگر از API گراف فیسبوک استفاده می‌کنید، در صورت بروز خطا یک پیام مانند زیر صادر کند:

1{
2  "error": {
3    "message": "(#803) Some of the aliases you requested do not exist: products",
4    "type": "OAuthException",
5    "code": 803,
6    "fbtrace_id": "FOXX2AhLh80"
7  }
8}

برخی نمونه‌ها نیز وجود دارند که در آن‌ها افراد یک URL با پیام خطا بازگشت می‌دهند که توضیحات بیشتری در مورد پیام خطا و همچنین روش مدیریت آن به دست می‌دهد.

از مشخصه‌های OpenAPI استفاده کنید

برای این که تیم‌های درون شرکت از اصول خاصی تبعیت کنند، بهره‌گیری از مشخصه‌های OpenAPI (+) می‌تواند مناسب باشد. OpenAPI امکان طراحی ابتدایی API و سپس اشتراک آن با مصرف‌کننده‌ها را به روشی آسان فراهم می‌سازد.

سخن پایانی

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

اگر این مطلب برای شما مفید بوده است، آموزش‌های زیر نیز به شما پیشنهاد می‌شوند:

• مجموعه آموزش‌های برنامه‌‌نویسی
• آموزش REST API در وردپرس برای کار با داده های پایگاه داده
• مجموعه آموزش‌های دروس علوم و مهندسی کامپیوتر
• API چیست؟ — به زبان ساده
• راهنمای تست API و نکاتی برای مبتدیان (SOAP و REST) – به زبان ساده

==