نقد و بررسی کتاب REST API Design Rulebook

نگاهی به محتوای کتاب ¹REST API Design Rulebook، نظر منتقدین، و لیستی از چند منبع دیگر برای آشنایی با وب‌سرویس، معماری REST،JAX-RS و الگو‌های‌طراحی در این حوزه، سرفصل‌های اصلی مقاله هستند.

نوشته‌ای که به نقد و بررسی یک کتاب می‌پردازد، می‌تواند دو گروه از مخاطبین را جذب کند. گروه اول کتاب را نخوانده‌اند و می‌خواهند بدانند «کتاب ارزش خواندن دارد یا نه؟» و گروه دوم که کتاب را خوانده‌اند، احتمالا می‌خواهند بدانند «نظر بقیه در مورد کتاب چیست؟»

اگر جزو گروه اول هستید، «چهار فصل اول خوب است، فصل ششم ارزش تورق دارد، اواخر فصل 4 و کل فصل 5 چندان دلچسب نیست». اگر می‌پرسید چرا؟ یا اگر جزو گروه دوم هستید در ادامه با ما همراه باشید:

مرور محتوای کتاب

فصل یک:  Introduction

فصل اول به مرور مفاهیم اصلی و تاریخچه وب اختصاص دارد. پایان نامه مشهور Roy Fielding در مورد معماری وب و اصولی که باعث می‌شود وب به شکل حاضر بتواند رشد کند، بررسی شده‌اند. در انتهای فصل اول، در نصف صفحه مفهوم WRML شرح داده می‌شود. نویسنده در شرح این کلمه می‌نویسد: «WRML یک فریم‌ورک مفهومی است که من برای طراحی و پیاده سازی REST API‌ها ساخته‌ام. اوایل، یک روش ساده برای طراحی دیاگرام‌های مدل‌سازی سرویس‌های REST با اشکال ساده هندسی بود، اما با معرفی application/wrml به عنوان Media Type توسعه پیدا کرد. در ادامه‌ی کتاب برای شرح Best Practice‌های طراحی وب‌سرویس، از این فریم‌ورک مفهومی و مفاهیمی که در کنار آن تعریف کرده‌ام استفاده خواهیم کرد.» نیمه‌ی دوم کتاب آمیخته با WRML است.

فصل دوم: Identifier Design with URIs

فصل دوم یکی از فصل‌های خوب کتاب است و به قواعدی اختصاص دارد که در طراحی URI‌های یک وب‌سرویس باید در نظر گرفته شوند. به چند مورد از قوانین ذکر شده در این فصل اشاره می‌کنیم:

• Resource‌ها باید در یک ساختار سلسله مراتبی مرتب شوند. URI باید نمایانگر این ساختار باشد. هر کاراکتر «/» نمایانگر پیمایش و یک مرتبه خُرد‌تر‌شدن در سلسله مراتب است.
• URI‌ها بعد از بخش domain به حروف کوچک و بزرگ حساس‌اند و برای رعایت یک‌نواختی، باید با حروف کوچک نوشته شوند.
• کلمات باید با کاراکتر خط تیره «-» از هم جدا شوند.
• نباید از کاراکتر «_» برای جدا کردن کلمات استفاده شود، چرا که اگر در یک صفحه‌ی وب URI ذکر شده و تبدیل به لینک شود، معمولا به صورت زیرخط دار نمایش داده می‌شود و تلاقی این دو خط می‌تواند باعث ابهام شود.
• …

در ادامه با عنوان «Resource Modeling»، اصول حاکم بر «هر بخش از URI» بررسی می‌شود². به این منظور «هر بخش از URI» که نماینده‌ی یک Resource است در یکی از چهار گونه‌ی اصلیِ معرفی شده در کتاب طبقه‎بندی شده و روشن می‌شود که هر گونه باید به شکل «اسم مفرد»، «‌اسم جمع»، «فعل» یا… ذکر شود. این طبقه‌بندی مفید و راه‌گشاست.

فصل سوم: Interaction Design with HTTP

فصل سوم به اصولی از پروتکل HTTP که طبیعتا در REST هم باید در نظر گرفته شود، اختصاص دارد. بخش اول فصل، کاربردهای مختلف هر کدام از متد های GET، HEAD، PUT، POST، DELETE و OPTIONS را بررسی می‌کند و به نکات جالبی اشاره می‌شود. به عنوان مثال، در یکی از قوانین آمده: از POST برای اجرای توابعی و عملیات‌هایی که در یکی از چهار گروه استاندارد CRUD نمی‌گنجند استفاده شود. هر کسی که شروع به مطالعه‌ی REST کرده باشد مطمئنا با این سوال مواجه شده: در موقعیت‌های مختلف Response Code استانداردی که باید فرستاده شود چیست؟ پاسخ این سوال در ادامه‌ی فصل داده شده‌ است.

فصل چهارم: Metadata Design

این فصل به سه بخش تقسیم می‌شود:

• در بخش اول در مورد تعدادی از HTTP Header‌ها و کاربرد‌های آن‌ها قواعدی ارائه می‌شود.
• بخش دوم مربوط به Media Type و انواع آن است.

این دو بخش، حاوی اطلاعات خوشخوان و مفیدی هستند.

• قسمت نامطلوب کتاب از بخش سومِ فصل، با عنوان «Media Type Design»، شروع می‌‎شود. طبیعتا خواننده هنگامی که درگیر مباحث گنگ این بخش می‌شود از خود می‌پرسد در طول دوره‌ی حرفه‌ای برنامه‌نویسی، چند بار مجبور به طراحی یک Media Type جدید خواهد بود!!؟ اما این تمام ماجرا نیست و Media Type‌ای که در این قسمت طراحی می‌شود (application/wrml)، بخش عمده‌ی قوانین و مثال‌های مطرح شده در ادامه‌ی کتاب را به خود اختصاص داده است. در واقع، نویسنده در این قسمت قصد آموزش طراحی یک Media Type جدید را ندارد، بلکه اصول اصلی طراحی WRML را معرفی می‌کند.

فصل پنجم: Representation Design

فصل پنجم، فصلی است که می‌تواند حوصله‌تان را سر ببرد، گیجتان کند یا شایستگی‌های کتاب تا این فصل را زیر سوال ببرد! همه چیز حول WRML  می‌چرخد.

نویسنده تاکید زیادی روی اهمیت ³HATEOAS دارد. صادقانه باید بگویم، قبل از مطالعه‌ی این قسمت نه کاملا HATEOAS را فهمیده بودم و نه به اهمیت آن پی برده بودم. ایده‌ی اصلی بحث این است که وب با داشتن لینک‌های متعدد از یک صفحه به صفحات دیگر، قابل مرور شد. در نوشته‌ی تاریخی Roy Fielding داشتن لینک‌های متداخل یکی از ویژگی‌های بنیادیِ معماری وب ذکر شده است. HATEOAS (تقریبا) به این مفهوم است که وقتی پیامی از طرف سرور برای Client فرستاده می‌شود باید حاوی لینک‌هایی باشد که امکان دسترسی به resource‌های مرتبط را فراهم کند تا پیمایش امکانات وب‌سرویس تا حد ممکن برای Client ساده‌تر شود. همچنین لینک‌های معقولی در موقعیت‌های مختلف باید فرستاده شود.

نویسنده‌ی کتاب معتقد است: Client باید بتواند، تنها با دسترسی به دامنه‌ی ریشه و بدون دانستن نکته‌ی دیگر در مورد API، تنها با استفاده از لینک‌های متداخل به کل وب‌سرویس و Resource‌های آن دسترسی داشته باشد. WRML Media Type و روش‌های استانداردی که نویسنده برای ارسال لینک‌های HATEOAS در یک پیام پیشنهاد می‌کند، در این راستا قابل تفسیر است. برخی از منتقدین کتاب تاکید بیش از حد نویسنده به معماری استاندارد API و HATEOAS تا آنجا که Client را بی‌نیاز از مستندات API کند، زیاده‌کاری⁴ می‌دانند و معتقدند لزومی به این حد از مستقل‌سازی API و Client نیست. نویسنده معتقد است باید تا حد ممکن از hard-Coding ویژگی‌های مربوط به معماری وب‌سرویس در Client اجتناب کرد تا امکان تغییر‌های بدون دغدغه در آن وجود داشته باشد.

فصل ششم: Client Concerns

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

• Client با استفاده از Query Parameter بتواند تعیین کند، کدام فیلد‌های داده فرستاده شود و کدام استثنا شود.
  • درخواست دریافت فیلد: (example.com/service?fields=fieldName)
  • صرف نظر از دریافت فیلد: (example.com/service?fields=!fieldName)
• Client با استفاده از Query Parameter بتواند تعیین کند، در پاسخ ارسالی، اطلاعات یک Resource فرستاده شود یا لینک آن.

نظر به این که بخش عمده‎ای از Client‌ها کد‌های جاوا‌اسکریپتی هستند که روی مرورگر‌ها اجرا می‌شوند، در ادامه، قانونی به نام «Same Origin Policy» ذکر می‌شود. به موجب این قانون کلاینت‎های جاوا‌اسکریپتی که در مرورگر اجرا می‌شوند، جهت حفظ امنیت و جلوگیری از نشت اطلاعات، تنها قادر به برقراری ارتباط با Resource‌ای هستند که خودشان هم متعلق به آنند. سپس دو راه حل به نام های JSONP و CORS برای رفع این محدودیت معرفی شده است.

مروری بر نظر دیگران

کتاب در سایت‌ها و وبلاگ‌های مختلفی نقد شده، همچنین کاربران Amazon و سایت Goodreads در مورد کتاب اظهار نظر کرده‌اند. آنچه در ادامه می‌آید، گزیده‌ای از نظرات است:

• این کتاب مجموعه‌ی خوبی از قوانینی است که هنگام ساخت یک وب‌سرویس Rest باید در نظر گرفته شوند، به جز بخش‌هایی که مربوط به WRML است، اگر نمی‌خواهید از این پیشنهاد نویسنده استفاده کنید، کتاب را بخوانید و سعی کنید اصولی که می‌خواهد پشت مثال‌های استفاده شده از WRML شرح دهد یاد بگیرید.
• به نظر من، فصل های اول تا سوم، و فصل ششم مفید بودند. اما حتی پس از اتمام مطالعه‌ی کتاب از خودم می پرسم WRML چه بود؟ و قرار بود کدام دغدغه‌ی من، به عنوان توسعهدهنده‌ی وب را رفع کند؟
• سرویس‌های زیادی هستند که برای ارتباطات خود از پروتکل HTTP استفاده می‌کنند و ادعا دارند از معماری REST استفاده کرده‌اند. در حالی که شاکله‌ی اصلی یک سرویس REST، توانایی آن در به‌کار‌گیری درست مفهوم HATEOAS است. مطالعه‌ی کتاب این نکته را برای من روشن کرد.
• حتی یک بار در دنیای واقعی توسعه و برنامه‌نویسی با WRML برخورد نکرده‌ام، حتی این مفهوم، فاقد یک صفحه‌ی ویکی‌پدیا است. در حالی که کتاب این مفهوم را در قلب تمام مباحث مطرح شده در نیمه‌ی دوم قرار می‌دهد، حال من حق دارم بپرسم اگر قرار نیست از این Media Type استفاده کنم، مطالعه‌ی قوانینی که حول آن نوشته شده‌اند بی ارزش نیست؟
• من احساس می‌کنم این کتاب «کمپین یک مرد تنها برای اقناع توسعه‌دهندگان، جهت پذیریش یک استاندارد» است.

مروری بر دیگر منابع

اگر به وب‌سرویس، معماری REST و بسته‌ی نرم‌افزاری JAX-RS علاقه‌مندید، می‌توانید به منابع زیر مراجعه کنید.

آشنایی با وب‌سرویس، تاریخچه و انواع
	Oline course Programming Foundations: Web Services (Lynda)
	Oline course Building Web Services with Java EE (Lynda)
آشنایی با معماری REST
	Book: RESTful Web APIs
	Book: REST in Practice
آشنایی با JAX-RS
	Book: RESTful Java with JAX-RS 2.0
	Book: Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON
اصول، قواعد و Best Practice‌های معماری REST
	Book: RESTful Java Patterns and Best Practices
	Book: RESTful Web Services Cookbook
	Book: Service Design Patterns

نظر شما در مورد این کتاب چیست؟ چه منابع دیگری در این حوزه می‌شناسید و توصیه می‌کنید؟

پانویس:

[1] -Masse, Mark. REST API Design Rulebook: Designing Consistent RESTful  Web Service Interfaces. “O’Reilly Media, Inc.”, 2011

[2] – Path Segment بخشی از URI است که که با کاراکتر «/» از قبل و بعدش جدا می‌شود.

[3] HyperMedia As The Engine Of Application State
[4] Overkill