کتاب The Design of Web APIs

کتاب The Design of Web APIs, 2nd Edition (طراحی APIهای وب، ویرایش دوم) راهنمایی جامع و کاربردی برای طراحی APIهای وب است که با تمرکز بر REST، مفاهیم، اصول و فرایندهای لازم برای ایجاد APIهایی کارآمد، ایمن، قابل استفاده و سازگار را آموزش می‌دهد.

کتاب The Design of Web APIs با بهره‌گیری از تجربیات نویسنده در طراحی و ارزیابی صدها API، به طراحان، توسعه‌دهندگان، نویسندگان فنی، تحلیل‌گران و حتی مصرف‌کنندگان API کمک می‌کند تا درک عمیق‌تری از معماری، مدل‌سازی داده، امنیت، تعامل‌پذیری، مستندسازی و نگهداری APIها به‌دست آورند. 

در ادامه مقدمه‌ای از کتاب The Design of Web APIs را از زبان نویسنده شرح خواهیم داد.

مقدمه‌ای بر کتاب The Design of Web APIs:

دوران حرفه‌ای من بیش از دو دهه به طول انجامیده، عمدتاً در حوزه مالی، و در این مدت روی اتصال نرم‌افزارها از طریق شبکه با استفاده از فناوری‌هایی مانند FTP، Sun RPC، CORBA، Java RMI، SOAP و APIهای وب کار کرده‌ام. من از APIهای داخلی و خارجی ضعیف (اعم از سرویس‌های وب، RPC و…) شکایت کرده‌ام و خودم هم بعضاً APIهای بدی طراحی کرده‌ام.

به چشم دیده‌ام که چگونه طراحی نادرست API می‌تواند باعث سردرگمی، طولانی شدن فرایند توسعه، کدهای شکننده، افزایش بدهی فنی، اتلاف منابع، سقوط در محیط اجرایی (production) و نقض‌های امنیتی شود.

با پیشرفت فناوری، اتصال نرم‌افزارها آسان‌تر شد، به‌ویژه با ظهور APIهای وب. رشد محصولات مبتنی بر مدل “as a service” و موفقیت APIهای عمومی مانند Twilio و Stripe در دهه ۲۰۱۰ سطح انتظارات را از طراحی API و تجربه توسعه‌دهنده بالا برد؛ اینکه بتوان تنها با چند خط کد پیامک ارسال کرد یا پول جابه‌جا کرد، انقلابی بود.

این تجربه دید من را نسبت به طراحی نرم‌افزار و API دگرگون کرد: با خودم فکر کردم چرا همیشه نمی‌توان چنین تجربه فوق‌العاده‌ای داشت؟ اما حتی پس از آغاز موج محبوبیت APIها، بسیاری از APIهای خصوصی و عمومی وب همچون نسل‌های قبلی خود نادیده گرفته شدند. اغلب آن‌ها صرفاً به چشم یک زیرساخت فنی دیده می‌شدند و حتی طراحان دلسوز نیز به دام اشتباهات رایجی می‌افتادند که من هم تجربه‌اش را داشته‌ام.

شرکت در اولین کنفرانس API (API Days Paris در اواخر ۲۰۱۴) مرا به اشتراک‌گذاری دانسته‌هایم ترغیب کرد. وبلاگ “API Handyman” را راه‌اندازی کردم، در کنفرانس‌ها سخنرانی کردم و نسخه اول کتاب The Design of Web APIs را نوشتم که در سال ۲۰۱۹ منتشر شد. در ابتدا قصد داشتم طراحی APIهای وب را با تمرکز بر REST، GraphQL و gRPC بررسی کنم، اما کتاب بیش از حد طولانی و پیچیده شد.

برای آموزش اصول طراحی، تصمیم گرفتم بر REST APIها تمرکز کنم، چون هم پرکاربرد هستند و هم بر پایه اصولی محکم بنا شده‌اند؛ این کار به من کمک کرد تا مسائل کلیدی طراحی مانند پاسخگویی به نیازها، قابلیت استفاده، امنیت، کارایی و قابلیت تغییر را پوشش دهم—مواردی که در مورد همه APIها صدق می‌کنند.

در سال ۲۰۲۵، نسخه اول کتاب The Design of Web APIs همچنان مرتبط است. APIهای وب در تمامی صنایع نقشی حیاتی دارند و برای سیستم‌های توزیع‌شده، اپلیکیشن‌های وب و موبایل، خودروها، لوازم خانگی، سایر نرم‌افزارها و هوش مصنوعی ضروری‌اند. REST APIها همچنان رایج‌ترین نوع API هستند. بررسی‌های طراحی، کارگاه‌ها، آموزش‌ها و تحلیل‌های بی‌شماری که انجام داده‌ام نشان می‌دهد که آموزش طراحی API همچنان ضروری است. بسیاری—including AI—در درک چیستی طراحی API و چگونگی ساخت APIهای مؤثر دچار مشکل‌اند.

بنابراین وقتی از من خواسته شد روی نسخه دوم کتاب The Design of Web APIs کار کنم، فوراً پذیرفتم. از زمان انتشار نسخه اول، تجربیات ارزشمندی کسب کرده‌ام و خواستم دانش جدید و به‌روزشده‌ام را در کتاب بگنجانم. می‌توان نسخه اول را با فیلم Terminator و نسخه دوم را با Terminator 2: Judgment Day مقایسه کرد: بزرگ‌تر و بهتر. داستان اصلی همان است (آموزش طراحی API وب با تمرکز بر REST، نه نجات بشر از اسکای‌نت)، اما این نسخه بازنویسی کامل با عمق بیشتر و محتوای بسیار بیشتر است.

برای مثال، یک فرایند طراحی API در آن ارائه شده که شاکله کتاب را شکل می‌دهد، بر اهمیت ارتباط با ذی‌نفعان دیگر تأکید می‌کند، قابلیت تعامل‌پذیری را بخشی از تجربه کاربری می‌داند، تصمیمات طراحی را ساده‌سازی می‌کند، به ساخت دستورالعمل‌ها و خودکارسازی آن‌ها می‌پردازد و شامل ۷۰ تمرین برای تثبیت مفاهیم کلیدی است. اگر نسخه جدید کتاب The Design of Web APIs را در گذشته داشتم، از بسیاری مشکلات اجتناب می‌کردم؛ امیدوارم برای شما هم مفید باشد!

درباره کتاب The Design of Web APIs
کتاب طراحی APIهای وب، ویرایش دوم با هدف کمک به شما در طراحی APIهای جدید یا اصلاح APIهای موجود نوشته شده است؛ به‌طوری که این APIها کارکرد مناسبی داشته باشند، همه‌کاره، ایمن و کارآمد باشند، محدودیت‌های محیطی را در نظر بگیرند و امکان تغییرات آینده را فراهم کنند.

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

چه کسانی باید کتاب The Design of Web APIs را بخوانند؟
طراحی APIهای وب، ویرایش دوم، طبیعتاً برای تمام کسانی است که به‌طور مستقیم در طراحی APIهای وب نقش دارند؛ اما برای افراد دیگری که در فرآیند ایجاد یا استفاده از آن‌ها مشارکت دارند نیز مفید است.

این افراد ممکن است توسعه‌دهندگان، تحلیلگران کسب‌وکار، نویسندگان فنی (که در توسعه برنامه‌های سمت سرور، میکروسرویس‌ها و بک‌اند اپلیکیشن‌های موبایل یا وب‌سایت‌ها مشارکت دارند)، رهبران فنی، معماران نرم‌افزار، متخصصان راهبری API (که در مقیاس وسیع روی چندین API کار می‌کنند) یا مالکان محصول API (که به‌دنبال ارائه بهترین تجربه ممکن برای توسعه‌دهندگان هستند) باشند.

همچنین، توسعه‌دهندگانی که از APIها استفاده می‌کنند، مهندسان QA که APIها را تست می‌کنند، نویسندگان فنی مستندساز، و متخصصان امنیتی که درخواست تغییراتی در APIها دارند نیز ممکن است با خواندن کتاب The Design of Web APIs درک بهتری از طراحی صحیح APIها پیدا کرده و بازخورد مؤثرتری به ارائه‌دهندگان API بدهند.

ساختار کتاب The Design of Web APIs: یک نقشه راه
این کتاب شامل ۴ بخش، ۱۹ فصل و یک پیوست است.
فصل ۱ کتاب The Design of Web APIs مقدمه‌ای بر کل کتاب است و در آن درکی مشترک از APIهای وب و طراحی آن‌ها ایجاد شده، و فرآیند و تمرین‌هایی که در فصل‌های بعدی خواهیم آموخت معرفی می‌شود.

بخش ۱ کتاب The Design of Web APIs: اصول طراحی یک API چندمنظوره و مناسب

• فصل ۲: نحوه شناسایی توانمندی‌هایی را که API باید ارائه دهد تا نیازها را به‌طور کامل و مناسب برآورده کند، توضیح می‌دهد.
• فصل ۳: APIهای REST را معرفی کرده و نحوه مشاهده قابلیت‌های API برای شناسایی عناصر لازم جهت طراحی یک REST API را آموزش می‌دهد: منابع، روابط آن‌ها و عملیات‌ها.
• فصل ۴: نحوه نمایش عملیات‌ها با استفاده از HTTP را بررسی می‌کند، از جمله طراحی مسیر منابع، انتخاب متدهای HTTP و وضعیت‌های HTTP و مکان داده‌ها در درخواست و پاسخ. همچنین سبک معماری REST و مزایای آن برای طراحی API مورد بحث قرار می‌گیرد.
• فصل ۵: به مدل‌سازی داده‌ها می‌پردازد؛ شامل منابع، پارامترهای مسیر، پارامترهای پرس‌وجو، و بدنه‌ها و هدرهای درخواست و پاسخ.
• فصل ۶: نحوه توصیف عملیات‌های HTTP با استفاده از OpenAPI Specification را نشان می‌دهد.
• فصل ۷: نحوه توصیف داده‌ها در اسناد OpenAPI با استفاده از JSON Schema را آموزش می‌دهد.

بخش ۲ کتاب The Design of Web APIs: طراحی APIهایی با کاربری آسان و قابلیت تعامل‌پذیری بالا

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

• فصل ۸: مفاهیم کاربرپسندی و تعامل‌پذیری را معرفی کرده و بر داده‌ها تمرکز دارد: چگونه داده‌ها را انتخاب، تعریف، نوع‌بندی، سازماندهی و نام‌گذاری کنیم تا آماده استفاده، منسجم و استاندارد باشند.
• فصل ۹: نحوه طراحی عملیات‌هایی واضح، قابل پیش‌بینی، با ورودی‌های آسان و خروجی‌های آماده استفاده را توضیح می‌دهد. همچنین به صفحه‌بندی، فیلترگذاری، مرتب‌سازی و مدیریت خطاها می‌پردازد.
• فصل ۱۰: طراحی توالی‌های عملیاتی مختصر، منعطف و با حداقل خطا را نشان می‌دهد.
• فصل ۱۱: به طراحی یک یا چند API، نام‌گذاری آن‌ها، و امکان مرور API از طریق HTTP و Hypermedia می‌پردازد.

بخش ۳ کتاب The Design of Web APIs: بررسی محدودیت‌هایی که طراحی ایده‌آل را تحت تأثیر قرار می‌دهند

در این بخش، عواملی مانند امنیت، کارایی، داده، معماری، کسب‌وکار و نیاز به تغییرات بررسی می‌شوند که می‌توانند طراحی ایده‌آل و کاربرپسند را محدود کنند:

• فصل ۱۲: طراحی APIهای ایمن را بررسی می‌کند؛ شامل حساسیت داده‌ها، رفتار امن عملیات، یکپارچگی داده و کنترل دسترسی با استفاده از scopeها.
• فصل ۱۳: بر طراحی کارآمدی تمرکز دارد که برای کاربران نهایی مزاحم نباشد و زیرساخت را تحت‌فشار قرار ندهد. شامل بهینه‌سازی حجم داده، کشینگ، پردازش چندعنصری و بررسی APIهای بهینه شده جداگانه.
• فصل ۱۴: بررسی تأثیر داده‌ها، معماری و الزامات کسب‌وکار بر طراحی؛ شامل فایل‌ها، عملیات طولانی، Webhookها و انواع دیگر API غیر از REST.
• فصل ۱۵: به موضوع تغییر دادن API می‌پردازد: چگونه بدون ایجاد اختلال در مصرف‌کنندگان، نسخه‌بندی کنیم و طراحی انعطاف‌پذیری داشته باشیم.

بخش ۴ کتاب The Design of Web APIs: آسان‌سازی و پایداری طراحی API در بلندمدت و مقیاس وسیع

• فصل ۱۶: نحوه تصمیم‌گیری طراحی با اعتمادبه‌نفس و ایجاد راهنماهای طراحی کاربرپسند برای APIها را توضیح می‌دهد.
• فصل ۱۷: بهینه‌سازی اسناد OpenAPI برای حفظ انسجام و آسان‌سازی نگارش آن‌ها، از جمله تعریف عناصر قابل استفاده مجدد در میان چند API.
• فصل ۱۸: خودکارسازی راهنماها برای حفظ یکنواختی و رهایی ذهن از جزئیات؛ همراه با مثال‌هایی از ابزار Spectral (یک linting tool برای API).

• فصل ۱۹: ارتقاء خروجی‌های طراحی برای ساخت یک «جعبه ابزار مرجع طراحی» که کار ما را تسهیل، پیاده‌سازی را دقیق‌تر و مراحل بعدی چرخه عمر API را پشتیبانی می‌کند.

سرفصل‌های کتاب The Design of Web APIs:

• The Design of Web APIs, Second Edition
• Praise for the first edition
• contents
• foreword
• preface
• acknowledgments
• about this book
• Who should read this book?
• How this book is organized: A roadmap
• About the code
• liveBook discussion forum
• Other online resources
• about the author
• about the cover illustration
• 1 What is API design?
• Part 1 Fundamentals of API design
  • 2 Identifying API capabilities
  • 3 Observing operations from the REST angle
  • 4 Representing operations with HTTP
  • 5 Modeling data
  • 6 Describing HTTP operations with OpenAPI
  • 7 Describing data with JSON Schema in OpenAPI
• Part 2 User-friendly, interoperable API design
  • 8 Designing user-friendly, interoperable data
  • 9 Designing user-friendly, interoperable operations
  • 10 Designing user-friendly, interoperable operation flows
  • 11 Designing user-friendly, interoperable APIs
• Part 3 Constrained API design
  • 12 Designing a secure API
  • 13 Designing an efficient API
  • 14 Adapting the API design to the context
  • 15 Modifying an API
• Part 4 Scaled and simplified API design
  • 16 Facilitating API design decision-making
  • 17 Optimizing an OpenAPI document
  • 18 Automating API design guidelines
  • 19 Enriching API design artifacts
• appendix-Solutions to the exercises
• index

جهت دانلود کتاب The Design of Web APIs می‌توانید پس از پرداخت، دریافت کنید.