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

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

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

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

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

این درخواست با کمک گرفتن از دستور curl اجرا می‌شود. همچنین ابزارهایی مانند Postman و REST Client وجود دارد که به شما این قابلیت را می‌دهد تا درخواست‌هایی را برای خروجی گرفتن از یک 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 چیست؟

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

بهترین رویکرد برای 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/v1 تغییر بدهید.

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

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

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

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

Accept: application/vnd.redkavasyl-v2+json

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

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

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

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

• 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 است، فرایند درخواست شما با موفقیت انجام شده، اما اگر با کدهای ۴۰۴، ۴۰۰ و یا ۵xx مواجه شدید بدانید که یک جای کار اشتباهی صورت گرفته است. 

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

• POST /users

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

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

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

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

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

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

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

• DELETE /users/123 – delete a user with id = 123

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

RESTful API چیست؟

مستندسازی

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

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

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

تفاوت REST و RESTful API

در حقیقت REST یک معماری است که امکان طراحی یک وب سرویس را به روش خاصی در اختیار توسعه دهنده قرار می دهد اما RESTful API یک سرویس است که این معماری را پیاده سازی کرده است. وب سرویس هایی که برپایه RESTful API ساخته میشوند، Stateless هستند به این معنی که به جای ذخیره‌سازی وضعیت کلاینت در سمت سرور، کلیهٔ داده‌ها در سمتِ خود کلاینت ذخیره می‌شوند و در هر درخواستی نیز برای سرور ارسال می‌شوند.

ویژگی‎های RESTful API:

• کلاینت-سرور (Client-Server): در این معماری کلاینت به‌عنوان front-end و سرور به‌عنوان back-end شناخته می‌شود. در این معماری حداقل وابستگی بین کلاینت و سرور وجود دارد، این اصل به توسعه دهنده ها اجازه می‌دهد تا بدون هیچ‌گونه وابستگی به یکدیگر به توسعه اپلیکیشن بپردازند.
• بدون وضعیت (Stateless): هیچ داده‎ای نباید در زمان پردازش انتقال درخواست روی سرور ذخیره شود و session باید در سمت کلاینت ذخیره شود. به عبارت دیگر، سرور هرگز نسبت به وضعیت درخواست‌های قبلی کلاینت اطلاعی ندارد. یکی از مزیت‌های کلیدی Stateless آن است که تغییرات صورت‌گرفته روی سرور هرگز کلاینت را با مشکل مواجه نمی‌کنند.
• قابل کش شدن (Cacheable): کلاینت باید قادر باشد که Response را به صورت Cache ذخیره کند.

• یکپارچگی رابط (Uniform Interface): برای دستیابی به Method های مختلف می‌باید از یک URL منحصر‌به‌فرد استفاده کرد به علاوه اینکه در Response می‌بایست با استفاده از Status code ها اطلاعات شفافی در اختیار کلاینت قرار دهیم.

در پایان

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

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

RESTful API چیست؟