آشنایی با RESTful API به زبان ساده

در دنیای مدرن توسعه نرم‌افزار، RESTful API یکی از مهمترین موضوعاتی است که توسعه دهندگان و مهندسین نرم‌افزار روزانه با آن سر و کار داشته و از آن استفاده می‌کنند. اما RESTful API چیست؟ دلیل اهمیت و استفاده بسیار زیاد از آن چیست؟ در این مطلب از وبسایت راکت قصد داریم شما را به صورت کامل و البته با زبان بسیار ساده با چیستی REST API آشنا کنیم و سپس از کاربردها و استفاده‌های آن بگوییم. اما پیش از آنکه سراغ REST API برویم، نیاز است ابتدا با خود API آشنا شویم.

منظور از API چیست؟

API یا Application Programming Interface که با رابط برنامه‌نویسی کاربردی ترجمه می‌شود یک مجموعه از قواعد و مکانیزم‌ها است که از طریق آن اپلیکیشن‌ها و یا کامپوننت‌های مختلف یک برنامه با همدیگر ارتباط برقرار می‌کنند. نام خود این مکانیزم بیانگر همین موضوع است. منظور از رابط چیزی‌ست که دو شئ یا دو موجودیت مختلف را به همدیگر ربط می‌دهد. اما بیایید کمی با جزئیات بیشتر از این موضوع صحبت کنیم. API می‌تواند داده‌هایی که شما برای اپلیکیشن‌تان نیاز دارید را از طریق یک فرمت مناسب به خروجی بفرستد و یا آن‌ را برگشت دهد. فرمت JSON و XML از این دست فرمت‌ها هستند. در این مطلب بیشتر در ارتباط با JSON که استانداردترین فرمت کنونی است صحبت خواهیم کرد.

بیایید به یک مثال نگاه کنیم. احتمالا با گیت‌هاب آشنایی دارید. این سرویس APIهای منحصر به فرد خود را دارد که از طریق آن می‌توانید به یکسری اطلاعات از کاربران، مخازن‌شان و… دسترسی داشته باشید. شما می‌توانید این داده‌ها را دریافت کنید و سپس برای پروژه‌ خودتان آن را تغییر دهید.

یک مثال از یک درخواست استاندارد برای API نمونه زیر است:

این درخواست با کمک گرفتن از دستور curl اجرا می‌شود. همچنین ابزارهایی مانند Postman و REST Client وجود دارد که به شما این قابلیت را می‌دهد تا درخواست‌هایی را برای خروجی گرفتن از یک API بفرستید. این دو ابزار همچنین برای تست APIها و مشاهده خروجی‌شان به ما کمک می‌کنند.

در زیر می‌توانید خروجی دستور بالا را مشاهده بکنید:

حال بیایید با مفهوم REST آشنا شویم. این کلمه اختصاری برای representational state transfer است. تعریف REST را به صورت ساده می‌توان اینطور بیان کرد: نمایش اطلاعات برای کاربران از راهی که خوانایی بالایی داشته باشد. یکی از مفاهیم اصلی که باید در ارتباط با REST بدانید این است که REST یک پروتکل یا استاندارد نیست، بلکه یک راه‌حل و یا یک سبک معماری برای نوشتن APIها است.

آشنایی عمیق‌تر با REST

حال که فهمیدیم REST چیست، درک کردن RESTful API بسیار ساده‌تر است. همانطور که گفته شد REST یک روش معماری و چیدمان است و حال RESTful را می‌توان مفسری برای REST دانست. برای مثال اگر شما یک سرور دارید و قسمت Back-End یک REST API دارد، اگر یک کاربر از قسمت Client-Side درخواستی را برای استفاده از API ارسال کند، کاربر شما Restful خواهد بود.

این معماری چگونه کار می‌کند؟

بهترین رویکرد برای RESTful API شامل چهار عملیات است:

دریافت داده از یک فرمت مناسب
ایجاد داده جدید
تغییر و بروزرسانی داده
حذف کردن داده

REST به شدت مبتنی بر HTTP است. قرار نیست که ما در ارتباط با این پروتکل توضیحی ارائه دهیم اما به نظر ارزشمند است که اگر بتوانیم اشاره‌ای به روند‌های اجرا عملیات‌های بالا در HTTP بکنیم.

هر کدام از عملیات‌های بالا حاوی متد HTTP منحصر به فرد خودشان هستند:

GET – متدی برای دریافت اطلاعات
POST – متدی برای ایجاد داده
PUT – متدی برای بروزرسانی و ایجاد تغییرات در داده
DELETE – متدی برای حذف

به صورت کلی به تمام این عملیات‌ها CRUD نیز گفته می‌شود که ما در بانک‌های اطلاعاتی با آن سر و کار داریم. این چهار عملیات، داده‌های ما را مدیریت می‌کنند.

REST یک رابط برای مدیریت درخواست‌ها و ارتباط با بانک اطلاعاتی دارد که می‌شود در جدول زیر آن را به صورت کلی مشاهده کرد:

تمام درخواست‌ها، حاوی جواب‌های منحصر به فرد خودشان هستند. این جواب‌ها از طریق یکسری کد ارائه می‌شوند که تعداد آن‌ها بسیار زیاد است. اما می‌شود آن‌ها را در ۵ کلاس دسته بندی کرد. عدد اول هر کلاس نمایانگر پیغامی است که زیرکلاس‌های آن ارائه می‌دهند:

1xx - informational;
2xx - success;
3xx - redirection;
4xx - client error;
5xx - server error.

اطلاعات بیشتر در ارتباط با این کدها را می‌توانید در این صفحه مشاهده کنید.

نسخه بندی

شما همیشه باید برای REST APIهای خودتان نسخه بندی مناسبی طراحی بکنید. برای مثال اگر URL مربوط به API شما http://example.com/api است، باید آن را به صورت http://example.com/api/v1 تغییر بدهید.

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

دو روش برای تعیین کردن نسخه وجود دارد. اولین حالت به این صورت است که شما آن‌ها را در URL تعیین می‌کنید که در بالا توضیح داده شد. حالت دوم نسخه‌ها را در درخواست‌های header مدیریت می‌کنید. معمولا به حالت اول انتقادات شدیدی وارد می‌شود و می‌گویند که آرگومان‌های بسیاری وارد URL می‌شود.

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

به صورت زیر از API استفاده نکنید:

Accept: application/vnd.redkavasyl-v2+json

شما می‌توانید بسیار ساده‌تر پارامترهای بیشتری را در سربرگ قرار دهید. بنابراین براساس تجربیات ما، بهترین رویکرد به صورت زیر خواهد بود:

Accept: application/vnd.redkavasyl+json; version=2.0

در این ارتباط می‌توانید این مطلب را مطالعه کنید.

طراحی معماری RESTful

تمام منابع در REST به صورت موجودیت یا Entity هستند. آن‌ها می‌توانند از همدیگر مستقل باشند. به مثال زیر دقت کنید:

GET /users - get all users
GET /users/123 - get a particular user with id = 123
GET /posts - get all posts

همچنین می‌توان به صورت ترکیبی از آن‌ها استفاده کرد. مثال:

GET /users/123/projects - get all the projects that a user with id = 123 has.

در مثال‌های بالا می‌تواند شاهد نقش کلیدی GET باشید که در تمام موارد قصد دریافت موجودیتی را دارد که شما درخواست می‌کنید. در این فرایند اگر خروجی شما کد ۲۰۰ باشد که به معنای OK است، فرایند درخواست شما با موفقیت انجام شده، اما اگر با کدهای 404، 400 و یا 5xx مواجه شدید بدانید که در یک جای کار اشتباهی صورت گرفته است.

همانطور که گفته شد متد POST می‌تواند برای ایجاد یک موجودیت جدید استفاده شود:

POST /users

وقتی که یک موجودیت جدید ایجاد می‌کنید، پارامترهایی را در بدنه درخواست خود بسازید. برای مثال:

{
  “first_name”: “Vasyl”,
  “last_name”: “Redka”
}

این درخواست اگر دوباره تکرار شود، موجودیت جدیدی را با یک ID متفاوت درست می‌کند. بنابراین شما در حقیقت چیزی که دریافت می‌کنید شبیه به زیر است:

{
  “id”: “1”,
  “first_name”: “Vasyl”,
  “last_name”: “Redka”
}

کد ۲۰۱ به این معنی است که روند ایجاد شما با موفقیت اعمال شده است.

درخواست بعدی PUT است که گفتیم برای ویرایش و ایجاد تغییر در یک موجودیت استفاده می‌شود. زمانی که شما این درخواست را می‌فرستید، بدنه دستور باید حاوی یک داده با قابلیت بروزرسانی باشد. برای مثال:

PUT /users/123 - upgrade a user entity with id = 123.

اگر تغییر به صورتی درست انجام شود، کد ۲۰۰ برای شما برگردانده می‌شود.

آخرین درخواست DELETE است که گفتیم برای حذف یک موجودیت براساس آی‌دی آن استفاده می‌شود:

DELETE /users/123 - delete a user with id = 123

این دستور نیز اگر با کد ۲۰۰ برگردانده شود به معنی موفقیت آمیز بودن‌ش است.

مستندسازی

برای مستندسازی یک فریمورک متن باز به نام Swagger.io وجود دارد که حقیقتا باید بگویم زندگی توسعه‌دهندگان را بسیار آسان‌تر می‌کند. شما می‌توانید با استفاده از این ابزار حتی کارهای مربوط به تستینگ را انجام دهید.

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

همچنین راه‌حلی بسیار منطقی به شما برای تعریف هر کدام از مدل‌های درخواستی را می‌دهد. شما می‌توانید فیلدها را با استفاده از داده‌ها مختلف پر کنید و آن‌ها را ارسال نمایید.

در پایان

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

امیدواریم که این مطلب توانسته باشد که به شما در درک درست RESTful API کمک کرده باشد. همچنین اگر از توسعه دهندگان NodeJS هستید و قصد توسعه REST APIهای خودتان را دارید می‌توانید از دوره آموزشی «ساخت Restful Api با Nodejs» استفاده کنید.