چه میزان از REST API می دونم؟

توهم دانش بدون دیدن
توهم دانش بدون دیدن

اگر برنامه نویس هستید یا توی دنیای نرم افزار دستی دارید، حتما REST API یا RESTful API به گوشتون خورده یا به شکلی با اون سر و کار داشتین. هدف این پست شرح REST API نیست.

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

به هر حال برای شروع، اون چه که توی restfulapi.net هست رو با هم مرور کنیم:

مفهوم REST

REST is acronym for REpresentational State Transfer. It is architectural style for distributed hypermedia systems and was first presented by Roy Fielding in 2000 in his famous dissertation.

در ادامه، مثل خیلی از معماری های دیگه، REST هم شش تا اصل راهنما داره که برای نام گذاری یک پروژه بعنوان RESTful لازمه رعایت بشن.

اصول راهنمای REST

۱- مفهوم Client-Server

با جدا سازی بخش های مربوط به رابط کاربری از بخش های مربوط به نگهداری Data می تونیم قابلیت نگهداری رابط کاربری توی Platform های مختلف رو بهینه کنیم و از طرفی با ساده سازی کامپوننت های سرور، قابلیت مقیاس پذیری هم بهتر می شه.

۲- مفهوم Stateless

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

بهتر بگم، از Cookie و Session خبری نیست، اونچه که لازمه برای اون درخواست به یاد بمونه باید به همراه Request ارسال بشه، بعنوان مثال ارسال JWT .

۳- مفهوم Cacheable

لازمه که داده های ارسالی در Response ها بصورت ضمنی یا صریح مشخص باشه که Cacheable هستند یا خیر. اگر Cacheable هست، کلاینت متوجه می شه که امکان Cache و استفاده از داده های ارسالی برای Request های آتی وجود داره.

۴- مفهوم Uniform interface

با اعمال اصل مهندسی نرم افزار به شکل عمومی برای اجزای رابط، معماری کلی سیستم ساده تر شده و حالت بصری تعاملات بهینه میشه. به عبارتی برای رسیدن به یک Uniform interface اصول متعددی لازمه تا چگونگی رفتار component ها رو نشون بده. REST با چهارتا اصل رابط، تعریف می شه:

  • identification of resources
  • manipulation of resources through representations
  • self-descriptive messages
  • hypermedia as the engine of application state

۵- مفهوم Layered Systems

سیستم های لایه بندی شده، امکان ایجاد یک معماری با hierarchical layers رو می ده که در اون رفتار component ها محدود شده . بعنوان مثال هر Component نمی تونه فراتر از لایه ای که در اون در حال تعامل با دیگر لایه هاست رو ببینه!

۶- مفهوم Code on demand (اختیاری)

توی REST این امکان وجود داره که عملکرد کلاینت با دانلود و اجرای script ها و applet ها وسیع تر بشه. با این امکان کلاینت ها می تونن به وسلیه ی کاهش تعداد Feature های مورد نیازی که از قبل آماده هستند، ساده تر بشن.

اگر شما بصورت کامل اصول رو پیاده کنید، یک RESTful API دارید و اگر نه REST API دارید.

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

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

- با داشتن یک پروژه ی REST API رابط های مختلفی می تونن با اون ارتباط برقرار کنن، لطفا لایه های کلاینت رو با اون، در هم قرار ندین. آدرس ها جدا هستن، محل اونها جداست(حتی اگه روی یک سرور هستند).

- در یک REST API از داشتن Session و Cookie و به کل نگهداری وضعیت ها توی سرور معذور هستیم. چرا که باید اصل State less بودن رو رعایت کنیم، این رو به این دید نگاه کنیم که یک API مشترک برای Mobile Application ها و Browser نوشتیم که تشکلیل شده از برنامه هایی روی IOS یا Android یا انواع مرورگرهاست، هیچ کدام از این موارد در تعامل با نگهداری State یکسان نیستند! در نهایت نیازی به نگرانی حالت در API برای درخواست ها نیست! هر چه لازم هست رو ارسال کنید.

- اگه Response هایی دارید که ممکنه بارها لازم بشن و تغییرات در اون ها مداوم نیست، می تونید اون رو Cache کنید، همونطور که اشاره شد این پاسخ ها می تونن با برچسب cacheable یا non-cacheable ارسال بشن تا کلاینت بتونه تشخیص بده.

- مورد شماره ی چهار اون لیست رو کمی جلو تر، مستقل بش می پردازم.

- مورد شماره پنج رو همه باید بدونید و نیازی به شرحش نمی بینم، اگه نمی دونیدش یا درک نمی کنید، سرچ کنید.

- آخری هم که اختیاری هست، خودم هنوز توی پروژه های گذشته و حال با اون برخورد نداشتم و لازم نبوده.

مفهوم Uniform interface

توی REST API به مواردی که کلاینت ها می خوان با اون ها کار کنن Resource می گیم، مثلا: کاربران، پست ها، کامنت ها و...

مورد اول: Identification of resources

نامگذاری Route ها برای دسترسی به منابع، که برای درک بیشتر کافیه این لینک رو مطالعه کنید.

مورد دوم: Manipulation of resources through these representations

به HTTP Verb ها برای دستکاری Resource ها اشاره داره، اگر حذف می کنید فعل DELETE یا دریافت می کنید فعل GET و برای ایجاد POST و ویرایش هم PUT، با یک سرچ متوجه می شید که موارد دیگه ای هم هست. هدف این پست شرح جزئیات اونها نیست.

مورد سوم:‌ Self-descriptive messages

مشخص هست، پیام های خود توصیف، کافیه اشاره کنم به HTTP Status Code ها، بلکه هر پیام شامل اطلاعات دقیقی هست که می گه چطور اون رو پردازش کنید. همچنین همونطور که قبلا گفتم پاسخ ها می گن که می تونید اون ها رو Cache کنید یا خیر.

اگر از HTTP Status Code ها استفاده می کنید، کم پیش میاد که تمام اونها لازمتون بشه، حتما سعی نکنید از تمامشون استفاده کنید.

مورد چهارم: HATEOAS

این بار مخفف رو گذاشتم، این مورد یکی از اصولی هست که باعث می شه REST نسبت به دیگر معماری های روی بستر شبکه، خاص باشه. اصطلاح hypermedia به هر محتوایی اشاره داره که لینک می ده به تصاویر و فیلم یا متن!

شما این امکان رو دارید که لینک های hypermedia ای رو بفرستید تا کلاینت بتونه بصورت داینامیک بین اونها و resource های مرتبط با اونها navigate کنه. به این منظور که کاربر بتونه به هدف نهایی خودش با کلیک کردن روی اون لینک ها برسه.

در ادامه مثال رو هم از سایت restfulapi.net آوردم:

تصور کنید که یه API با متد GET (که آدرس رو هم می بینید) پاسخ JSON زیر رو ارسال می کنه:

//Address: http://api.domain.com/management/departments/10
//Response:
{
    &quotdepartmentId&quot: 10,
    &quotdepartmentName&quot: &quotAdministration&quot,
    &quotlocationId&quot: 1700,
    &quotmanagerId&quot: 200,
    &quotlinks&quot: [
        {
            &quothref&quot: &quot10/employees&quot,
            &quotrel&quot: &quotemployees&quot,
            &quottype&quot : &quotGET&quot
        }
    ]
}

همونطور که می بینید یک لیست links با اون ارسال شده که اشاره می کنه به ارتباط با employees و این که این لینک چه آدرسی داره و با چه فعلی Call می شه. کارمندان مربوط به اون دپارتمان با لینکی که اشاره شده قابل دسترسی هستند.

دقت کنید که این پاسخ حاوی لینک هایی با ارتباط مستقیم به همون Resource ای هست که درخواست شده بوده. تصور کنید که یک کاربر رو دریافت می کنید، می تونید به پست های اون با یک لینک دسترسی پیدا کنید.

در انتها:

این اصول بسته به زبان یا Framework خاصی نیست، بلکه عمومی است. اگر شما تمام موارد شش گانه را رعایت نمی کنید(کم بودنشان در طراحی شما، نه این که با تصور شخصیتان اشتباه پیاده کرده باشید) آسمان به زمین نمی آيد، و اگر تازه کار نیستید با یک نگاه مشخص است که کجا ممکن است موردی را پوشش ندهید.

تشکر بابت وقتی که گذاشتی و خوندی.

لینک هایی که استفاده کردم یا مفید هستن:

https://restfulapi.net/

https://restfulapi.net/statelessness/

https://restfulapi.net/hateoas/

https://restfulapi.net/http-status-codes/

https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/