نام‌گذاری ریسورس‌های RESTful API
در آموزش گذشته، با مفهوم ریسورس آشنا شدیم. اساساً یکسری به اصطلاح Best Practice در نحوهٔ نام‌گذاری ریسورس‌های RESTful API وجود دارد که با پیروی از آن‌ها می‌توانیم وب سرویسی در اختیار سایر توسعه‌دهندگان قرار دهیم که با کمترین میزان سردرگمی شروع به استفاده از آن کنند که در ادامه با برخی از مهم‌ترین آن‌ها آشنا خواهیم شد.
استفاده از 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 که به منظور ایجاد ریسورس جدید است برای چنین اندپوینتی می‌باید محدود گردد.