RESTful API به زبان ساده چیست؟

[Mohamad]

در این مطلب ابتدا سعی داریم تا شما را با مفهوم API آشنا کنیم، سپس در ارتباط با ‌HTTP می‌گوییم، در ارتباط با REST صحبت می‌کنیم و در نهایت یک مثال ساده از شیوه کار و معماری RESTful API را به شما نشان می‌دهیم.

[Mohamad]

یک مقدار تئوری

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




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

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

[Mohamad]

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





دقیق‌تر شدن در REST

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

[Mohamad]

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

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

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

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

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

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




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

• ۱xx - informational;
• ۲xx - success;
• ۳xx - redirection;
• ۴xx - client error;
• ۵xx - server error.

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

نسخه بندی

شما همیشه باید برای REST APIهای خودتان نسخه بندی مناسبی طراحی بکنید. برای مثال اگر URL مربوط به API شما

 http://example.com/api

است، باید آن را به صورت

http://example.com/api/v۱

تغییر بدهید.

[Mohamad]

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

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

Accept: application/vnd.redkavasyl-v2+json 

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

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

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

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

• GET /users - get all users
• GET /users/۱۲۳ - get a particular user with id = ۱۲۳
• GET /posts - get all posts

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

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

در مثال‌های بالا می‌تواند شاهد نقش کلیدی GET باشید که در تمام موارد قصد دریافت موجودیتی را دارد که شما درخواست می‌کنید. در این فرایند اگر خروجی شما کد ۲۰۰ باشد که به معنای OK است، فرایند درخواست شما با موفقیت انجام شده، اما اگر با کدهای ۴۰۴، ۴۰۰ و یا ۵xx مواجه شدید بدانید که یک جای کار اشتباهی صورت گرفته است.
همانطور که گفته شد متد POST می‌تواند برای ایجاد یک موجودیت جدید استفاده شود:

POST /users

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

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

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

 {

  “id”: “1”,

  “first_name”: “Vasyl”,

  “last_name”: “Redka”

}

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

PUT /users/۱۲۳ - upgrade a user entity with id = ۱۲۳.

اگر تغییر به صورتی درست انجام شود، کد ۲۰۰ برای شما برگردانده می‌شود.
آخرین درخواست DELETE است که گفتیم برای حذف یک موجودیت براساس آی‌دی آن استفاده می‌شود:

DELETE /users/۱۲۳ - delete a user with id = ۱۲۳

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

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

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

امیدواریم که این مطلب توانسته باشد که به شما در درک درست RESTful API کمک کرده باشد.