اصول وب سرویس RESTful

با بخش چهارم از اصول وب سرویس RESTful با شما همراه هستیم .در مقالات قبلی تمام آموزش های مورد نیاز برای ساخت وب سرویس restful بر اساس معماری و قوانین REST را دیدیم (وب سرویس REST چیست).

در این بخش قصد داریم به شما در اعمال محدودیت , استفاده از HATEOAS و .. به عنوان یکی از اصول پیشنهادی در طراحی API های RESTful اشاره کنیم.

اعمال محدودیت (limit) بر روی فیلد های خروجی API

همان طور که گفته شد برای آن که کاربران بتوانند به یک یا چند منبع دسترسی پیدا نمایند باید در خواستی را با متد GET به سرویس شما ارسال نمایند. در پاسخ به درخواست آن ها دو رویکرد وجود دارد.

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

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

صرفه جویی شده و پاسخ به کاربر با سرعت بیشتری می رسد.

برای این منظور پیشنهاد می شود همانند آنچه در مورد search گفتیم عمل شود. مثلا پارامتری با نام fields در URL در نظر بگیرید و به کاربر این امکان را دهید تا فیلد های مورد نیازش را بصورت comma separated به API اعلام نماید. در زیر نمونه ای از این نحوه کار آورده

شده است :

GET /users?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

1	GET /users?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

استفاده از نام های مستعار برای برخی از پرس و جو های رایج

برخی از پرس و جو ها ممکن است بسیار رایج و مورد استفاده باشند. بد نیست برای راحتی کار استفاده کنندگان API های خود این پرس و جو ها را در قالب URL های خاصی در اختیار آنها قرار دهید. به عنوان مثال گرفتن آخرین لیست آخرین محصولات را می توانید در قالب

یک مسیر مجزا مثلا GET /products/recently_added در اختیار کاربران قرار دهید.

اعمال محدودیت (limit) بر روی فیلد های خروجی API

همان طور که گفته شد برای آن که کاربران بتوانند به یک یا چند منبع دسترسی پیدا نمایند باید در خواستی را با متد GET به سرویسشما ارسال نمایند. در پاسخ به درخواست آن ها دو رویکرد وجود دارد. یکی آن که همیشه کل فیلد های منبع یا منابع را باز گردانید و یا آنکه

آنچه را که مورد نیاز کاربر است در اختیار وی قرار دهید.

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

هم آنکه اطلاعات اضافی و غیر ضروری در اختیار کاربران قرار نمی گیرد. علاوه بر این در پهنای باند شبکه صرفه جویی شده و پاسخ به کاربر با سرعت بیشتری می رسد.

شده است : پس از انجام عملیات درج و بروزرسانی منبع را نیز بازگردانید

همانطور که گفتیم فراخوانی های PUT، POST و PATCH برای اعمال تغییرات بر روی منابع استفاده میشوند. از آنجایی که در بسیاری از مواقع برنامه نویسان پس از اعمال اینگونه تغییرات، می خواهند منبع تغییر یافته یا ایجاد شده را نمایش دهند و یا از آن استفاده نمایند،

پیشنهاد می شود برای جلوگیری از فراخوانی مجدد جهت دریافت منبع ، منبع تغییر یافته در پاسخ بازگردانده شود تا برای استفاده های آتی در اختیار برنامه نویسان قرار گیرد.

در مورد POST دقت کنید که بهتر است در پاسخ علاوه بر خود منبع، کد HTTP 201 ( به معنی دریافت موفقیت آمیز درخواست ) و ساخته شدن یک منبع جدید در سرور است (به فرض ایجاد یک فایل یا صفحه جدید)، ارسال کد ۲۰۱ تنها در صورتی صحیح است که

سرور منبع جدید را ساخته باشد، در غیر اینصورت (اگر منبع هنوز ساخته نشده باشد) باید کد ۲۰۲ را ارسال کند.) را بازگردانید. علاوه بر آن هدر مربوط به Location را نیز با آدرس مربوط به منبع جدید مقدار دهی نمایید.

استفاده از HATEOAS

استفاده از HATEOAS یکی از موارد بحث بر انگیز در هنگام طراحی API های REST است. برخی از طراحان معتقند که لینک های مربوط به برنامه کلاینت باید توسط خود کلاینت (یا بهتر بگوییم برنامه نویس کلاینت) ایجاد گردد و سرویس تنها نقش پاسخ دهی به درخواست ها

را بر عهده دارد.

اما برخی دیگر معتقدند که در سرویس های REST طراحی باید بر مبنای HATEOAS صورت پذیرد. بدین معنی که API وظیفه دارد نحوه تعامل کلاینت با سرویس را از طریق فراهم کردن لینک هایی در پاسخ تعیین نماید.

به بیانی دیگرسرویس علاوه بر داده وظیفه دارد فرا داده هایی (metadata) را در اختیار کلاینت قرار دهد و از طریق آن لینک هایی که در آینده مورد استفاده کلاینت است را برای کلاینت فراهم کند. بعنوان مثال در هنگام گرفتن لیستی از کاربران از سرویس در صورتی که

صفحه بندی (pagination) برای نمایش کاربران داشته باشیم، علاوه بر لیست کاربران در فراداده لینک های صفحه بعدی و صفحه قبلی را در اختیار کلاینت قرار می دهیم.

اگر چه HATEOS یکی از اصول REST است و پیاده سازی آن بسیار خوب است، اما بنظر می رسد هنوز استاندارد ها و ابزار های مورد نیاز برای پیاده سازی آن محیا نمی باشد و نیاز به کار بیشتر دارد.

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

کلاینت داده کمتری را مجبور است ذخیره و نگهداری نماید.

در ادامه مقاله آموزشی اصول وب سرویس RESTful به نامگذاری پارامتر ها , انواع خروجی های معتبر و .. می پردازیم . با ما همراه باشید .

امیدوارم با به کارگیری این اصول وب سرویس RESTful در طراحی های API بتوانید میزان توسعه پذیری , خوانایی و استفاده آسان از آن را تا حد زیادی افزایش بدید و به اصول استاندارد آن برسید .

موفق پیروز باشید.