خانه >> کامپیوتر >> ۷ قانون در طراحی REST API URI

۷ قانون در طراحی REST API URI

۷ قانون در طراحی REST API URI

هفت قانون در طراحی Rest API
هفت قانون در طراحی Rest API

قبل از  اینکه بحث در مورد قوانین را شروع کنیم، بهتر است با بعضی اصطلاحات آشنا شویم.

URI

REST API ها از Uniform Resource Identifiers (URI) یا شناسانهٔ یکنواخت منبع برای آدرس دهی به منابع(resources) استفاده میکنند. امروزه در دنیای وب، طرح های متفاوتی از URI وجود دارد از طرح های بینظیری که به وضوح منابع را دریافت و ارتباط بین اجزای آنها را مشخص میکنند، مثل:

۱. http://api.example.com/louvre/leonardo-da-vinci/mona-lisa

تا آنهایی که به سخت قابل درک هستند مثل این:

۲. http://api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66

یک نکته رو اینجا بگم، شاید منظور از واژه منابع یا resources را متوجه نشده باشید. آدرس اولی را در نظر بگیرید. مثلا در این URI همانطور که میبینید موزه louvre شامل بخش های مختلفی می‌شود که یک بخش از آن به هنرمند معروف leonarodo-da-vinci  اختصاص داده شده و همچنین یکی از آثار این هنرمند تابلو نقاشی mona-lisa است. خوب در اینجا louvre یک منبع یا resource به حساب می آید، که ما توانستیم با این URI به این منبع متصل شویم و اطلاعات مربوط به آن را دریافت کنیم. اینطوری 🙂

موزه لوور پاریس
موزه لوور پاریس

خوب است با فرمت URI و نام بخش های مختلف آن آشنا شوید. این یک سینتکس کلیست که RFC 3986  تعریف کرده:

URI = scheme “://” authority “/” path [ “?” query ] [ “#” fragment ]

#۱: نباید از اسلش (/) در انتهای URI ها استفاده کرد

استفاده از اسلش به عنوان آخرین کاراکتر در مسیر یک URI، هیچ ارزش معنایی نداشته و حتی میتواند باعث سردرگمی نیز بشود. در انتهای REST API ها نباید از اسلش استفاده کرد.

بسیاری از وب کامپوننت ها و فریمورک‌ها دو URI زیر را یکسان در نظر می‌گیرند:

http://api.canvas.com/shapes/
http://api.canvas.com/shapes

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

API خوب کاربر را از یک URI که آخرش (/) قرار گرفته به URI که این کاراکتر ازش حذف شده باشد ریدایرکت یا منتقل میکند.

#۲: استفاده از کارکترهای جداکننده (/) برای نشان دادن رابطه سلسه مراتبی بین منابع در URI

کاراکتر‌های (/) در قسمت path از URI استفاده می‌شوند تا یک رایطه سلسه مراتبی بین منابع (resources) نشان دهند.

برای مثلا:

http://api.canvas.com/shapes/polygons/quadrilaterals/squares

در مثال بالا می‌بینید که چطور از کل(shapes) به جزء (squares) رسیدیم. و این موارد با کاراکتر (/) از هم جدا شده اند.

#۳: استفاده از کاراکتر خط فاطمه (-) برای خوانایی بیشتر در URI

در بخش هایی از مسیر(path) URI که چند کلمه بکار رفته آنها را با کارکاتر (-) از هم جدا کنید تا خوانایی بیشتری داشته باشند.مثل:

http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

#۴: در URI نباید از کاراکتر (ـ) یا Underscore استفاده کرد

همانطور که می‌دانید اپلیکیشن های ویرایش متن، مرورگرها و .. اغلب URI ها را با قرار دادن یک خط در زیر آن (underline) نمایش میدهند، بر با توجه به نوع فونت ممکنه کاراکتر‌(ـ) در زیر این خط قرار گرفته و پنهان شود.

برای جلوگیری از این مسئله، از خط فاصله (-) بحای خط زیر(ـ) استفاده کنید.

#۵: در مسیر URI بهتر است از حروف کوچک استفاده شود

حروف کوچک در بخش path از URI به حروف بزرگ ترجیح داده میشوند چون استفاده از حروف بزرگ بعضی مواقع باعث ایجاد خطا میشود. و قانون RFC 3986 می‌گوید که URI ها حساس به کوچکی و بزرگی حروف هستند. بجز بخش schema و host آنها.

برای مثال:

۱. http://api.example.com/my-folder/my-doc

۲ .HTTP://API.EXAMPLE.COM/my-folder/my-doc

این دو URI صحیح می‌باشند و هیچ تفاوتی با یکدیگر ندارند.

۳ .http://api.example.com/My-Folder/my-doc

اما این URI با URI شماره ۱ یکسان نبوده و ممکن است باعث به وجود آمدن مشکلاتی شود.

#۶: پسوند نباید در URI قرار بگیرد

در وب، کاراکتر  (.) نقطه جهت جدا کردن نام فایل از پسوند آن استفاده میشود.

گاهی در REST API از پسوند جهت مشخص کردن نوع پیام ارسالی استفاده میکنند که این درست نیست و برای این کار باید از هدر Content-Type استفاده شود تا مشخص کنیم محتوای ارسالی چگونه باید پردازش شود.

http://api.college.com/students/3248234/courses/2005/fall.json
http://api.college.com/students/3248234/courses/2005/fall

#۷: باید از نام های جمع استفاده کرد یا مفرد؟

برای صدا زدن منابع ما یک قانون کلی را اساس کار قرار میدهیم: همه چیز را به صورت جمع در نظر بگیر حتی اگر درست به نظر نرسد! خوب این باعث میشود هماهنگی بین URI ها به وچود بیاید. مثلا: students/32343

اما روایط بین منابع را چگونه نمایش می‌دهیم؟ مثلا فرض کنید یک دانشجو تعدادی دوره های آموزشی را گذرانده است. آن را به این شکل نشان می‌دهیم:

http://api.college.com/students/3248234/courses

با این API لیست تمام دوره هایی که دانشجوی با آی دی ۳۲۴۸۲۳۴ گذرانده را دریافت میکنیم.

یا یک مثال دیگر:

http://api.college.com/students/3248234/courses/physics

این API لیست دوره‌های فیزیکی که دانشجوی با آی دی ۳۲۴۸۲۳۴ گذرانده دریافت میشود.

۷ قانون در طراحی REST API URI
به این مطلب امتیاز بدهید 🙂

درباره ی حسین ندائی

حسین ندائی

یک دیدگاه

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

14 − 6 =