آشنایی با اصول نام‌گذاری صحیح ریسورس‌ها در معماری RESTful API


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

استفاده از Noun به جای Verb در نام‌گذاری ریسورس‌ها

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

Collection به مجموعه‌ای از ریسورس‌های مرتبط به هم اشاره دارد که برای نام‌گذاری آن‌ها باید از اسامی جمع استفاده کرد به طوری که داریم:

GET http://example.com/api/users

برخی دولوپرها اقدام به مشخص کردن فرمت خروجی در یوآرآی می‌کنند به طوری که مثلاً داریم:

GET http://example.com/api/users.json

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

یک ریسورس از جنس Document اصولاً به یک رکورد در دیتابیس اشاره دارد که برای ریسورس‌هایی از این دست می‌باید از اسامی مفرد یا یک شناسه استفاده کرد:

GET http://example.com/api/users/1

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

POST http://example.com/api/users/1/articles

در واقع، در مثال فوق قصد داریم تا برای کاربری با شناسهٔ ۱ مقاله‌ای ثبت کنیم. حال اگر همین یوآرای را با متد GET به صورت زیر فراخوانی کنیم:

GET http://example.com/api/users/1/articles

کلیهٔ‌ مقالات کاربری با شناسهٔ ۱ ریترن خواهد شد.

این بخش از محتوا مخصوص کاربرانی است که ثبت‌نام کرده‌اند.
جهت مشاهدهٔ این بخش از محتوا لاگین نمایید.

آشنایی با یکسری Anti Pattern در نام‌گذاری ریسورس‌ها

به طور کلی، منظور از اصطلاح Anti Pattern یکسری روش‌های اشتباه است که دولوپرها در توسعهٔ نرم‌افزار استفاده می‌کنند که در ادامه قصد داریم تا برخی از آن‌ها در پروسهٔ‌ نام‌گذاری در فرآیند توسعهٔ RESTful API را برشمریم.

پیش از این هم اشاره کردیم که استفاده از پارامترها برای فیلتر کردن دیتا مناسب است اما به منظور دستیابی به یک ریسورس خاص روش مناسبی نیست:

GET http://example.com/api/services?op=update_customer&id=12345&format=json

با استفاده از یوآرال فوق، قصد داریم تا یک تَسک آپدیت انجام دهیم که به طور معمول برای این منظور از متد PUT استفاده می‌شود اما این در حالی است که در مثال فوق از متد GET استفاده شده که معمولاً برای فراخوانی دیتا مورد استفاده قرار می‌گیرد. به عنوان مثال اشتباه دیگری نیز می‌توان یوآرال زیر را مد نظر قرار داد:

GET http://example.com/api/customers/12345/update

با توجه به اینکه پیش از این گفتیم در نام‌گذاری این معماری به جای افعال می‌باید از اسامی استفاده کرد، درج update در یوآل‌ال فوق غیرضروری است چرا که صرفاً با استفاده از متد اچ‌تی‌تی‌پی مناسب، که در این مثال PUT است، می‌توانیم به مقصود خود برسیم:

PUT http://example.com/api/customers/12345/update

این مثال کماکان مشکل دارد چرا که کلمهٔ update منجر به سردرگمی توسعه‌دهنده خواهد شد تا جایی که به منظور بهبود آن می‌توان یوآرال زیر را در نظر گرفت:

PUT http://example.com/api/customers/12345

پیش از این گفتم که باید از اسامی جمع برای ریسورس‌ها استفاده نماییم اما ممکن است این سؤال پیش آید که «آیا می‌توان گاهی از اسامی مفرد نیز استفاده کرد؟» که پاسخ به این پرسش «آری» است به طوری که مثلاً داریم:

GET|PUT|DELETE http://example.com/api/customers/12345/configuration

با توجه به اینکه هر یوزر فقط و فقط یک کانفیگ (پیکربندی یا تنظیمات) دارا است، پس دیگر لزومی ندارد که این ریسورس را به صورت جمع و به شکل configurations استفاده کنیم. همچنین لازم به یادآوری است با توجه به اینکه هر کاربر فقط یک کانفیگ می‌تواند داشته باشد، پس استفاده از متد POST که به منظور ایجاد ریسورس جدید است برای چنین اندپوینتی می‌باید محدود گردد.



بهزاد مرادی

لیست نظرات
کاربر میهمان
دیدگاه شما چیست؟
کاربر میهمان