RESTful Web API Patterns and Practices Cookbook Connecting and Orchestrating Microservices and Distributed Data (Mike Amundsen) (z-library.sk, 1lib.sk, z-lib.sk)

Page 1

Mike Amundsen Foreword by Matt McLarty RESTful Web API Patterns & Practices Cookbook Connecting and Orchestrating Microservices and Distributed Data A m und sen

Page 2

SOF T WARE ARCHITEC TURE “Amundsen has delivered a valuable resource that addresses common and complex API design choices in an easy-to-understand format. Along the way, he helps the reader tap into the power of the HTTP protocol and hypermedia. Anyone faced with designing evolvable web-based APIs that will stand the test of time should read this book.” —James Higginbotham Author of Principles of Web API Design, Executive API Consultant, LaunchAny RESTful Web API Patterns & Practices Cookbook US $59.99 CAN $74.99 ISBN: 978-1-098-10674-4 Twitter: @oreillymedia linkedin.com/company/oreilly-media youtube.com/oreillymedia Many organizations today orchestrate and maintain apps that rely on other people’s services. Software designers, developers, and architects in those companies often work to coordinate and maintain apps based on existing service APIs, including third-party services that run outside their ecosystem. This cookbook provides proven recipes to help you get those many disparate parts to work together in your network. Author Mike Amundsen provides step-by-step solutions for finding, connecting, and maintaining applications designed and built by people outside the organization. Whether you’re working on human-centric mobile apps or creating high- powered machine-to-machine solutions, this guide shows you the rules, routines, commands, and protocols—the glue—that integrate individual APIs so they can function together in a safe, scalable, and reliable way. • Design and build individual service interfaces that can successfully interact on the open web • Increase interoperability by designing APIs that share a common understanding • Build client applications that can adapt to evolving services without breaking • Create resilient and reliable APIs that support peer-to- peer interactions on the web • Use web-based API registries to support runtime “find and bind” operations that manage external dependencies in real time • Implement stable workflows to accomplish complex, multiservice tasks consistently Mike Amundsen is an internationally known author and speaker who travels the world consulting and talking about network architecture, web development, and the intersection of technology and society.

Page 3

Praise for RESTful Web API Patterns and Practices Cookbook Creating scalable and reliable web APIs and efficiently consuming them is challenging, maybe even more challenging than you think. This cookbook is full of recipes and principles to help you face those known and unknown challenges. —Arnaud Lauret, API Handyman, OpenAPI Lead, Postman This book does an excellent job of making good API design more accessible. Look up the challenge you’re facing, and you’ll find a recipe with a solution and an explanation of how it works. —Erik Wilde, Catalyst, Axway Mike Amundsen did it again with excellent best practices and examples of best of breed API patterns. Easy to read, understand, and apply. —Vicki Reyzelman, Director of Platform and Governance Amundsen has delivered a valuable resource that addresses common and complex API design choices in an easy-to-understand format. The book contains plenty of examples and diagrams to demonstrate the purpose and application of each recipe. Along the way, he helps the reader tap into the power of the HTTP protocol and hypermedia. Anyone faced with designing evolvable web-based APIs that will stand the test of time should read this book. —James Higginbotham, Author of Principles of Web API Design, Executive API Consultant, LaunchAny

Page 4

More Books by Mike Amundsen API Strategy for Decision Makers (2022) with Derric Gilling Continuous API Management, 2nd ed. (2021) with Medjaoui, Wilde, and Mitra Design and Build Great Web APIs (2020) What Is Serverless? (2020) API Traffic Management 101 (2019) Continuous API Management, 1st ed. (2018) with Medjaoui, Wilde, and Mitra RESTful Web Clients (2017) Microservice Architecture (2016) with Nadareishvili, Mitra, and McLarty RESTful Web APIs (2013) with Leonard Richardson Building Hypermedia APIs with HTML5 and Node (2011)

Page 5

Mike Amundsen RESTful Web API Patterns and Practices Cookbook Connecting and Orchestrating Microservices and Distributed Data

Page 6

978-1-098-10674-4 [LSI] RESTful Web API Patterns and Practices Cookbook by Mike Amundsen Copyright © 2023 Amundsen.com, Inc. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://oreilly.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or corporate@oreilly.com. Acquisitions Editor: Melissa Duffield Indexer: WordCo Indexing Services, Inc. Development Editor: Angela Rufino Interior Designer: David Futato Production Editor: Katherine Tozer Cover Designer: Karen Montgomery Copyeditor: Sonia Saruba Illustrator: Kate Dullea Proofreader: Piper Editorial Consulting, LLC October 2022: First Edition Revision History for the First Edition 2022-10-14: First Release See http://oreilly.com/catalog/errata.csp?isbn=9781098106744 for release details. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. RESTful Web API Patterns and Practi‐ ces Cookbook, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. The views expressed in this work are those of the author, and do not represent the publisher’s views. While the publisher and the author have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the author disclaim all responsibility for errors or omissions, including without limitation responsibility for damages resulting from the use of or reliance on this work. Use of the information and instructions contained in this work is at your own risk. If any code samples or other technology this work contains or describes is subject to open source licenses or the intellectual property rights of others, it is your responsibility to ensure that your use thereof complies with such licenses and/or rights.

Page 7

This book is dedicated to the memory of architect and design theorist Christopher Alexander (1936–2022). Thanks for helping me see the big picture while I continue to focus on the possible.

Page 8

(This page has no text content)

Page 9

Table of Contents Foreword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii About This Book xiii Conventions Used in This Book xx Using Code Examples xx O’Reilly Online Learning xxi How to Contact Us xxi Acknowledgments xxii Part I. Understanding RESTful Hypermedia 1. Introducing RESTful Web APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 What Are RESTful Web APIs? 4 Why Hypermedia? 9 Shared Principles for Scalable Services on the Web 16 2. Thinking and Designing in Hypermedia. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Establishing a Foundation with Hypermedia Designs 21 Increasing Resilience with Hypermedia Clients 26 Promoting Stability and Modifiability with Hypermedia Services 33 Supporting Distributed Data 40 Empowering Extensibility with Hypermedia Workflow 46 vii

Page 10

Part II. Hypermedia Recipe Catalog 3. Hypermedia Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 3.1 Creating Interoperability with Registered Media Types 60 3.2 Ensuring Future Compatibility with Structured Media Types 62 3.3 Sharing Domain Specifics via Published Vocabularies 64 3.4 Describing Problem Spaces with Semantic Profiles 68 3.5 Expressing Actions at Runtime with Embedded Hypermedia 73 3.6 Designing Consistent Data Writes with Idempotent Actions 76 3.7 Enabling Interoperability with Inter-Service State Transfers 79 3.8 Designing for Repeatable Actions 84 3.9 Designing for Reversible Actions 87 3.10 Designing for Extensible Messages 91 3.11 Designing for Modifiable Interfaces 95 4. Hypermedia Clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 4.1 Limiting the Use of Hardcoded URLs 103 4.2 Coding Clients to Be HTTP Aware 107 4.3 Coding Resilient Clients with Message-Centric Implementations 110 4.4 Coding Effective Clients to Understand Vocabulary Profiles 113 4.5 Negotiating for Profile Support at Runtime 116 4.6 Managing Representation Formats at Runtime 119 4.7 Using Schema Documents as a Source of Message Metadata 123 4.8 Every Important Element Within a Response Needs an Identifier 128 4.9 Relying on Hypermedia Controls in the Response 132 4.10 Supporting Links and Forms for Nonhypermedia Services 135 4.11 Validating Data Properties at Runtime 139 4.12 Using Document Schemas to Validate Outgoing Messages 141 4.13 Using Document Queries to Validate Incoming Messages 147 4.14 Validating Incoming Data 150 4.15 Maintaining Your Own State 153 4.16 Having a Goal in Mind 156 5. Hypermedia Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 5.1 Publishing at Least One Stable URL 165 5.2 Preventing Internal Model Leaks 167 5.3 Converting Internal Models to External Messages 171 5.4 Expressing Internal Functions as External Actions 176 5.5 Advertising Support for Client Response Preferences 181 5.6 Supporting HTTP Content Negotiation 186 5.7 Publishing Complete Vocabularies for Machine Clients 190 viii | Table of Contents

Page 11

5.8 Supporting Shared Vocabularies in Standard Formats 196 5.9 Publishing Service Definition Documents 202 5.10 Publishing API Metadata 206 5.11 Supporting Service Health Monitoring 210 5.12 Standardizing Error Reporting 216 5.13 Improving Service Discoverability with a Runtime Service Registry 220 5.14 Increasing Throughput with Client-Supplied Identifiers 224 5.15 Improving Reliability with Idempotent Create 228 5.16 Providing Runtime Fallbacks for Dependent Services 232 5.17 Using Semantic Proxies to Access Noncompliant Services 238 6. Distributed Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 6.1 Hiding Your Data Storage Internals 247 6.2 Making All Changes Idempotent 251 6.3 Hiding Data Relationships for External Actions 256 6.4 Leveraging HTTP URLs to Support “Contains” and “AND” Queries 260 6.5 Returning Metadata for Query Responses 264 6.6 Returning HTTP 200 Versus HTTP 400 for Data-Centric Queries 270 6.7 Using Media Types for Data Queries 274 6.8 Ignoring Unknown Data Fields 280 6.9 Improving Performance with Caching Directives 285 6.10 Modifying Data Models in Production 291 6.11 Extending Remote Data Stores 298 6.12 Limiting Large-Scale Responses 302 6.13 Using Pass-Through Proxies for Data Exchange 307 7. Hypermedia Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 7.1 Designing Workflow-Compliant Services 317 7.2 Supporting Shared State for Workflows 322 7.3 Describing Workflow as Code 325 7.4 Describing Workflow as DSL 329 7.5 Describing Workflow as Documents 331 7.6 Supporting RESTful Job Control Language 334 7.7 Exposing a Progress Resource for Your Workflows 338 7.8 Returning All Related Actions 342 7.9 Returning Most Recently Used Resources 346 7.10 Supporting Stateful Work in Progress 350 7.11 Enabling Standard List Navigation 358 7.12 Supporting Partial Form Submit 363 7.13 Using State-Watch to Enable Client-Driven Workflow 366 7.14 Optimizing Queries with Stored Replays 375 7.15 Synchronous Reply for Incomplete Work with 202 Accepted 381 Table of Contents | ix

Page 12

7.16 Short-Term Fixes with Automatic Retries 387 7.17 Supporting Local Undo or Rollback 391 7.18 Calling for Help 396 7.19 Scaling Workflow with Queues and Clusters 400 7.20 Using Workflow Proxies to Enlist Noncompliant Services 403 8. Closing Remarks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 Applying These Recipes 407 Transforming Existing Services 410 Additional Resources 411 Next Steps 412 A. Guiding Principles of RESTful Web APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 B. Additional Reading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 C. Related Standards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 D. Using the HyperCLI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 x | Table of Contents

Page 13

Foreword Oh, what a tangled web we’ve woven! I started my career in technology when the World Wide Web was first being used in the business arena. In fact, the common thread throughout my career has been apply‐ ing the lessons of the web to the complex world of enterprise architecture and digital business strategy, especially those web APIs that seem to be at the center of everything. In 2012, I had the pleasure of teaming up with Mike Amundsen. We’ve partnered on many API-themed endeavors since, and I’ve never stopped learning from him. It was Mike who taught me the fundamental principles of the web and so much more. It never ceases to amaze me how Mike is able to find insights I overlooked that seem so obvious in hindsight. RESTful Web API Patterns and Practices Cookbook puts many of these principles and insights into one very practical package. When the internet first hit the mainstream back in the early ’90s, I was at a small undergraduate school getting a mathematics degree. My professors were the ones most excited at first, which makes sense, I guess, given the web’s academic roots. I used to have to pry them away from reading other people’s movie reviews to get back to our algebra lessons. In those musty, book-laden campus offices, it wasn’t obvious at all that the World Wide Web would become the most transformative human inven‐ tion of my lifetime, and arguably of all time. So how did we go from pixelated bulletin boards of personal interests to a world where 70% of business transactions take place digitally? A lot of the credit has to go to the fact that the web was cooked up using a fairly simple set of ingredients: clients, servers, networks, open protocols, and, of course, APIs. No matter how complex and ubiquitous the web gets, those ingredients remain at its core. xi

Page 14

Hyperlinks—or hypermedia, as a more encompassing term—have had a particularly profound impact on technology. Originally modeled after academic citations (the professors again), not only were hyperlinks the ingredient that brought the network effect to the web, but they have also shaped user expectations for all technology since. There was no user manual for the web, just some blue underlined text that encour‐ aged users to rely on intuition. This “follow your nose” principle is something Mike has always emphasized, and it provides an important perspective when considering APIs and the role of hypermedia. So the world may not need a user manual for the web, but it certainly needs a devel‐ oper guide. On this topic, Mike has already authored or coauthored a number of essential books: RESTful Web APIs, RESTful Web Clients, Microservice Architecture, and Continuous API Management to name a few. RESTful Web API Patterns and Prac‐ tices Cookbook continues this work. Here, you will not only learn how the technolo‐ gies of the web are foundational to current computing, but also how the way that the web works is fundamental to scalable architecture in current software ecosystems. Mike parallels the principles of the web with de rigueur API design, illustrating how these principles can be applied successfully. Most of all, you will learn how to archi‐ tect and build systems that are resilient to change and last the test of time. Every organization is compounding the complexity of their software landscapes on a continual basis, and increasingly connecting with partners and suppliers in a digital ecosystem. If you want the recipes to thrive in that reality, this is the cookbook for you. —Matt McLarty, Global Field CTO of MuleSoft at Salesforce Vancouver, August 2022 xii | Foreword

Page 15

Preface Welcome to the world of the RESTful Web API Patterns and Practices Cookbook. That’s quite a moniker—one worth explaining and exploring. And that’s what we’ll be doing in this preface. I will tell you now that I’m going to break the rules a bit and include a substantial amount of pertinent text in the front matter of this book (front matter is all these pages with roman numerals as page numbers). I’ll save the details for the next section (Part I). Let’s first take care of some logistics. About This Book The goal of this book is to enable software designers, architects, developers, and maintainers to build service interfaces (APIs) that take advantage of the strengths of the web, while lowering the costs and risks of creating reliable high-level services that hold dependencies on other APIs and services reachable only over the network. To do that, I’ve gathered a collection of more than 70 recipes and patterns that I’ve learned and used over the several decades I’ve spent helping clients design, build, and deploy successful business services on the open web. I suspect you will be familiar with at least some of the recipes you’ll find here—possibly by other names or in dif‐ ferent forms. I also hope that you will find novel approaches to similar problems. Over the years, I’ve found that the challenges of software design rarely change. The solutions to those problems change frequently based on technology advances and fashion trends. We’ll focus on the challenges in this book, and I’ll leave the up-to-date technology and fashion choices to you, the reader. Since this is a cookbook, there won’t be much runnable code. There will, however, be lots of diagrams, code snippets, and network message examples along with explana‐ tions identifying the problems. The challenges and discussion will always be technol‐ ogy and platform agnostic. These recipes are presented in a way that will let you xiii

Page 16

translate them into code and components that will work within your target environment. Who Should Read This Book The primary audience for the book is the people tasked with planning, architecting, and implementing service interfaces that run over HTTP. For some, that will mean focusing on creating enterprise-wide service producers and consumers. For others, it will mean building services that can live on the open web and run in a scalable and reliable way for consumers across the globe. For all, it will mean creating usable appli‐ cation programming interfaces that allow programmers to solve the challenges before them. Whether you are hosting your solutions locally on your own hardware or creating software that will run in the cloud, the recipes here will help you understand the chal‐ lenges and will offer a set of techniques for anticipating problems and building in recovery to handle cases where the unanticipated occurs. What’s Covered Since the book is meant to be useful to a wide audience, I’ve divided it into chapters focused on related topics. To start, Chapters 1 and 2 make up Part I of the book, where we explore the background and foundations of shared services on the web. To stretch the cookbook analogy, consider Part I as the story behind the “hypermedia cusine” we’ll be exploring in Part II. Like any good cookbook, each of the main chap‐ ters in Part II contains a set of self-contained recipes that you can use to meet particu‐ lar challenges as you design, build, and deploy your web API “dishes.” Online Resources The book has a number of associated online resources, including a GitHub repository and related web pages, some examples, and the latest updates to the recipe catalog. You can reach all these resources via http://WebAPICookbook.com. Here is a quick listing of the chapters and what they cover. Part I: Understanding RESTful Hypermedia The opening chapters (Chapters 1 and 2) describe the foundation that underpins all the recipes in the book. They are a mix of history, philosophy, and pragmatic think‐ ing. These are the ideas and principles that reflect the lessons I’ve learned over my years of designing, building, and supporting network software applications running on the web. xiv | Preface

Page 17

Chapter 1, Introducing RESTful Web APIs This is a general overview of the rationale behind the selected recipes in this book. It includes a section answering the question “what are RESTful web APIs (RWAs)?,” reasons hypermedia plays such an important role in the creation of RWAs, and some base-level shared principles that guide the selection and explan‐ ation of the recipes in this book. This chapter “sets the table” for all the material that follows. Chapter 2, Thinking and Designing in Hypermedia This chapter explores the background of hypermedia-driven distributed systems that form the foundation for web applications. Each recipe collection covered in Part II (design, clients, services, data, and workflow) is explored with a mix of history, philosophy, and pragmatic thinking. Reading this chapter will help you understand some of the key design ideas and technical bases for all the patterns and practices outlined in the rest of the book. Part II: Hypermedia Recipe Catalog Part II holds all the recipes I’ve selected for this volume. You’ll notice that most of the chapters start with the word “hypermedia.” This should give you a clue to the overall approach we’ll be taking throughout the book. Chapter 3, Hypermedia Design Reliable and resilient services start with thoughtful designs. This chapter covers a set of common challenges you’ll need to deal with before you even get to the level of coding and releasing your services. This chapter will be particularly helpful to architects as well as service designers, and helps set the tone for the various rec‐ ipes that follow. Chapter 4, Hypermedia Clients This chapter focuses on challenges you’ll face when creating service/API con‐ sumer applications. I made a point of discussing client apps before talking about recipes for service interfaces themselves. A common approach for creating flexi‐ ble and resilient service consumers is necessary for any program that plans on creating a stable and reliable platform for open services that can live on the web as well as within an enterprise. Chapter 5, Hypermedia Services With a solid foundation of design principles and properly architected client applications, it can be easier to build and release stable service producers that can be safely updated over time without breaking existing API consumers. This set of recipes focuses not only on principles of solid service interface design but also on the importance of supporting runtime error recovery and reliability patterns to make sure your solutions stay up and running even when parts of your system experience failures. Preface | xv

Page 18

Chapter 6, Distributed Data This chapter focuses on the challenges of supporting persisted data in an online, distributed environment. Most of the recipes here are aimed at improving the responsiveness, scalability, and reliability of your data services by ensuring data integrity—even when changing internal data models and implementations at runtime. Chapter 7, Hypermedia Workflow The last set of recipes focuses on creating and managing service workflow on the web. The key challenge to face for open services workflow is to create a safe and reliable set of solutions for enlisting multiple unrelated services into a single, resilient workflow to solve a problem none of the individual services knows any‐ thing about. I saved this chapter for last since it relies on many of the recipes cov‐ ered earlier in the book. Chapter 8, Closing Remarks The final chapter is a short wrap-up of the material as well as a “call-forward” to help you decide on your own “next steps” as you set out to apply these recipes to your environment. Appendices There are a series of appendices for the book that you can use as additional support materials. These are sometimes referred to in the text but can also be treated as stand- alone references. Appendix A, Guiding Principles This appendix is a short “motivational poster” version of the single guiding prin‐ ciple behind the selected recipes, as well as some secondary principles used to shape the description and, ultimately, the implementation of these patterns in general. Appendix B, Additional Reading Throughout the book, I’ll be recommending additional reading, quoting from books and articles, and calling out presentations and videos that are the source of much of the advice in the book. This appendix contains a self-standing list of reading and viewing materials that you can use as references and a guide when working through the recipes. Appendix C, Related Standards Since the goal of this book is to create services that can successfully live “on the web,” the recipes depend upon a number of important open web standards. This appendix contains a list of the related standards documents. xvi | Preface

Page 19

Appendix D, Using the HyperCLI In several places in the book, I reference a command-line interface tool called HyperCLI. You can use this tool to interact with hypermedia-aware services. This appendix provides a short introduction to the tool and some pointers to other online resources on how to take advantage of HyperCLI and HyperLang. What’s Not Covered As a book of recipes, this text is not suited for teaching the reader how to implement the patterns and ideas listed here. If you are new to any of the pillars upon which this book is built, you’ll want to look to other sources for assistance. The following books are some that I have used in training and consulting engage‐ ments on topics not covered in detail in this book: HTTP protocol Most of the recipes in this book were developed for HTTP protocol implementa‐ tions. For more on the power and challenges of HTTP, I recommend the HTTP Developer’s Handbook by Chris Shiflett (Sams). Shiflett’s text has been a great help to me in learning the inside details of the HTTP protocol. Published in 2003, it is still a valuable book that I highly recommend. API design For details on designing APIs for distributed services, I suggest readers check out my Building Hypermedia APIs with HTML5 and Node (O’Reilly). For those look‐ ing for a book focused on coding APIs, my more recent book, Design and Build Great Web APIs (Pragmatic Bookshelf), offers a detailed hands-on guide to the full API lifecycle. API clients The work of coding API/service clients is a skill unto itself. For an extended look at the process of creating flexible hypermedia-driven client applications, I refer readers to my RESTful Web Clients (O’Reilly). Web APIs For details on creating web APIs themselves, I encourage readers to check out the book RESTful Web APIs (O’Reilly), which I coauthored with Leonard Richard‐ son, and my book Design and Build Great Web APIs (O’Reilly). Other books I keep close at hand include Principles of Web API Design by James Higginbotham (Addison-Wesley) and Arnaud Lauret’s The Design of Web APIs (Manning). Data For more on handling data at scale, I recommend Data Management at Scale by Piethein Strengholt (O’Reilly) and Data Governance: The Definitive Guide by Evren Eryurek et al. (O’Reilly). Preface | xvii

Page 20

Workflow The books Practical Process Automation by Bernd Ruecker (O’Reilly) and Service Orchestration as Organization by Malinda Kapuruge et al. (O’Reilly) are a good place to start exploring the world of workflow engineering. There are many other sources of sage advice on designing and building distributed services, and you’ll find a list of suggested reading in Appendix B. About These Recipes While the recipes in this cookbook are grouped by topic (design, client, server, data, registry, and workflow), each recipe within the chapters follows the same general pattern: Problem This is a short description of the problem you may run into as you design and build your services. Solution This section is a narrative of the suggested solution (or solutions) you can employ to solve the stated problem. Example In some cases, the recipe will include an example. This might be an HTTP mes‐ sage exchange (request/response) or even a short snippet of pseudocode to show an internal workflow related to the solution. Discussion Recipes will also contain a more lengthy discussion section where trade-offs, downsides, and advantages are covered. Often this is the most important section of the recipe, since very few of these challenges have just one possible solution. Related Recipes Many of the recipes will end with a list of one or more other related recipes cov‐ ered elsewhere in the book. Some recipes rely on other recipes or enable them, and this is where you’ll learn how the recipes interact with each other in actual running systems. How to Use This Book I highly recommend reading the book from start to finish to get the full effect of the concepts and recipes contained here. However, I also recognize that time may be short and that you might not need a total immersion experience in order to get the benefits of the book. With this in mind, here are a couple of different ways you can read this book, depending on your focus, goals, and the amount of time you want to devote to the text. xviii | Preface