شروع RESTful API در جاوا

از سری مقالات آموزش Java Enterprise, مبحث RESTful API را برمی‌گزینیم.

RESTFul Web Service بر پایه Representational State Transfer و یا به اختصار REST قرار دارد. معماری REST برپایه منابع است و برای دسترسی به منابع مورد استفاده قرار می‌گیرد. حال این منابع می‌تواند تصاویر موجود در Server, متون و یا سایر اطلاعات ذخیره شده باشد.استفاده از REST برای ایجاد API برنامه های تحت وب, بسیار متداول است و علت این امر نیز سبکی و تعریف راحت آن است. وقتی با استفاده از مرورگر یک سایت را باز می‌کنید, یک صفحه HTML برای شما به نمایش در می‌آید. چون طراح سایت مطمئن است که یک شخص این درخواست را ارسال کرده است, بنابراین نتیجه باید جلوه های ظاهری را نیز شامل شود. اما وقتی از API استفاده می‌کنید, اطلاعات خام, در قالب JSON و یا XML, برای کاربر ارسال می‌شود.

برای شروع, ابتدا تعریف Web Service را مورد بررسی قرار می‌دهیم. Web Service ها را می‌توان Service هایی در Internet درنظر گرفت که برنامه نویس می‌تواند به آنها دسترسی پیدا کند. Web Service ها, Online API هایی هستند که می‌تواند از طریق کد ها فراخوانی شوند. وقتی می‌خواهیم از یک Service در جاوا استفاده کنیم, نیاز است تا آن سرویس و کلاس های آن را از طریق Maven و یا روش های مشابه به پروژه اضافه کنیم. اما در Web Service, این کلاس ها در فضاهای دیگری وجود دارند و ما تنها متد های مورد نیاز را در بستر شبکه فراخوانی می‌کنیم.

همانطور که از نام Web Service برمی‌آید, اطلاعات از طریق Web و HTTP جابجا می‌شوند. به این ترتیب که Client یک درخواست (Request) را به Server ارسال می‌کند و Server یک پاسخ (Respone) را برمی‌گرداند. اطلاعات دریافت شده در client می‌تواند برای پردازش و یا مقدار دهی جلوه های ظاهری استفاده شود, اما مابین Client و Server, تنها اطلاعات خام رد و بدل می‌شود.

وقتی از HTTP برای جابجایی اطلاعات استفاده می‌کنیم, این سوال پیش می‌آید که از کدام متد موجود در HTTP باید استفاده شود؟ ساختار معین و قانون ثابتی برای اینکه از کدام متد HTTP باید استفاده شود, وجود ندارد. در واقع به هنگام طراحی API, این متد ها تعیین می‌شوند و در توضیح API قرار داده می‌شود.

REST API مانند صفحات وب, یک آدرس مختص به خود دارد. اما این آدرس برخلاف آدرس صفحات وب, Resource Base است. برای مثال آدرس زیر را در نظر بگیرید:

zerotohero.ir/?subject=java

این آدرس مختص به یک صفحه وب است که نتایجی مرتبط با جاوا است را نشان می‌دهد. اما آدرس زیر یک آدرس API است:

zerotohero.ir/subject/java

این آدرس به یک API اختصاص دارد. وقتی برای یک Web Application می‌خواهیم آدرس قرار دهیم, نوع آدرس اهمیت کمتری دارد. چون کاربران با استفاده از جلوه های ظاهری و با استفاده از کلیک میان لینک ها جابجا می‌شود. اما وقتی یک API طراحی می‌کنید, نوع آدرس بسیار حائز اهمیت است. زیرا تنها راه ارتباط با منابع, آدرس است.

مبحث بعدی Metadata است. ما برای Client آدرس و متد HTTP مورد نیاز برای فراخوانی را تعریف کردیم واطلاعات برای Client ارسال شد. این اطلاعات علاوه بر اطلاعات خام مورد نیاز, یکسری اطلاعات اضافی دیگری را نیز شامل می‌شود. یکی از این اطلاعات اضافی Status Code نام دارد. Status Code یک عدد است که به عنوان اولین مقادیر ارسالی از سمت Server می‌باشد. این عدد مشخص می‌کند که پردازش به درستی انجام شده و یا با خطایی مواجه شده است. عدد ۲۰۰ نشان دهنده نتیجه موفقیت آمیز, عدد ۵۰۰ نشان دهنده خطا Server و عدد ۴۰۴ خطا معروف Not Found است. لیست کامل Status Code را می‌توانید در اینجا مشاهده کنید. داده مهم دیگری که در Metadata وجود دارد, Content-type است. این مقدار مشخص می‌کند که اطلاعات ارسال در چه قالبی است. لیست کامل Content-type ها را می‌توانید در اینجا مشاهده کنید.

فرض کنید یک نرم افزار اجتماعی داریم و می‌خواهیم برای آن یک API ایجاد کنیم. در این برنامه یک کاربر یک صفحه شخصی دارد که اطلاعات هویتی کاربر در آن وجود دارد. هر کاربر می‌تواند یک مطلب را منتشر کند و کاربران دیگر می‌توانند برای وی نظر بگذارند و یا مطلب وی را Like کنند. بنابراین چهار جدول در پایگاه داده این برنامه نیاز داریم. یک جدول برای نگهداری اطلاعات کاربران, یک جدول برای نگهداری مطالب منتشر شده, یک جدول برای نظرات و یک جدول هم برای Like ها در نظر می‌گیریم. اکنون باید Resource URI را برای این API ایجاد کنیم. برای صفحات کاربران به این صورت آدرس دهی می‌کنیم:

URL.com/profiles/{profile_name}

به این ترتیب آدرس ما برای دسترسی به صفحه شخصی کاربر وجود دارد و تنها باید مقدار مورد نظر را بجای profile_name قرار دهیم. این حالت بسیار شبیه به حالتی است که چندین صفحه را به صورت static تعریف کنیم و با قراردادن نام هر صفحه, به اطلاعات آن دسترسی پیدا کنیم. در اینجاست که Resource Base بودن API معنا پیدا می‌کند. توجه داشته باشید که برای نام‌گذاری از کلمات استفاده کنید. برای مثال این آدرس:

URL.com/getProfile/{profile_name}

اشتباه است. همچنین نام ها باید به صورت جمع باشد. برای مثال بهتر است از profiles بجای profile استفاده کنید. یکی از ویژگی های بسیار مهم تعریف آدرس API این است که اگر تغییراتی در شیوه ایجاد برنامه مانند تغییر framework رخ دهد, آدرس API می‌تواند بدون تغییر باشد, بدون اینکه مصرف کنندگان با مشکلی مواجه شوند.

در تعریف آدرس باید به ارتباط میان موجودیت ها نیز توجه کنید. فرض کنید دو مطلب داریم که یکی از مطالب سه نظر و دیگری دو نظر برایشان ثبت شده است. برای این منظور هر نظر را زیر مجموعه یک پست قرار می‌دهیم و دسترسی به آن را به این صورت می‌نویسم: