Preface

This journey to writing this book started almost 10 years ago. It is the result from thousands of hours of training, tens of thousands of miles traveled, and too many written words and lines of code to count. It comprises insights from organizations across the globe that were just starting their API journey or had already begun the adventure. The book incorporates the insights of API practitioners across the world that I have had the pleasure to meet.

Yet, the journey really started almost 25 years ago, when I first entered the software profession. So many advisors provided their insight via books and articles. Mentors along the way helped to shape my way of thinking about software. They laid the foundation of how I prefer to realize software architecture.

Maybe the journey really started almost 40 years ago, when my grandfather gifted me with a Commodore 64. He was a civil engineer and cost engineer who attended night school while working to support his family during the day. He was thirsty for knowledge, reading and absorbing everything he could. He always made us laugh when he said, “I’m still amazed at how television works!” after seeing a computer operate. Yet, he was the one that gifted me that magical computer, saying “computers are going to be big some day and my grandson should know how to use one.” This single action started a life-long love of software development for me.

In reality, the journey started more than 70 years ago when the pioneers of our current age of computing established many of the foundational principles we still use today to construct software. Though technology choices change, and the trends come-and-go, it all builds upon the work of so many in the software industry and beyond. There are so many men and women that helped to carve the way for what we do today.

What I am saying is that APIs would not be what they are today without all the hard work that came before us. Therefore, we must thirst for understanding “the how” and “the why” behind what we do today. Then, we must seek to apply these lessons to all that we do tomorrow. Along the way, we need to find ways to inspire others to do the same. This is what my grandfather and father taught me, so I pass this lesson on to you. This book reflects the things I’ve learned thus far in my journey. I hope you gain some new insights by building upon what is presented here while you seek to prepare the next generation.

Who Should Read This Book

This book is for anyone that wants to design a single API or a series of APIs that will delight humans. Product owners and product managers will gain a deeper understanding of the elements that teams need to design an API. Software architects and developers will benefit from learning how to design APIs by applying principles of software architecture. Technical writers will identify ways that they can contribute not just to the clarity of API documentation but add value throughout the API design process. In short, it is for everyone involved in API design whether you are in a development or non-development role.

About This Book

This book outlines a series of principles and process for design APIs. The design process is designed for individuals and cross-functional teams to help navigate the complexities of API design. It encourages an outside-in perspective on API design by applying concepts such as the voice of the customer, jobs to be done, and process mapping. While the book walks through a greenfield example from the ground-up, the book may also be used for existing APIs.

The book covers all aspects of API design, from requirements to arriving at an API design ready for delivery. It also includes guidance on how to document the API design for more effective communication between you, your team, and your API consumers. Finally, the book touches on a few elements of API delivery that may have an impact on your API design.

The book is divided into five parts:

Part I: Introduction to Web API Design – an overview of why API design is important and an introduction to the API design process used in this book

Part II: Aligning on API Outcomes – ensures alignment between the team designing the API and all customers and stakeholders

Part III: Defining Candidate APIs – identifies the APIs necessary to deliver the desired outcomes, including the API operations required, into API profiles

Part IV: Designing APIs – transforms the API profiles into one or more API styles that meet the needs of the target developers. Styles covered include REST, gRPC, GraphQL, and event-based asynchronous APIs.

Part V: Refining the Design – improves the API design based on insights from documentation, testing, and feedback. It also includes a chapter on decomposing APIs into microservices. Finally, the book closes with tips on how to scale the design process in larger organizations.

For those that need a refresher on HTTP, the language of the web used for web-based APIs, Appendix A provides a nice primer to help you get started.

What’s Not in the Book

There are no code listings, other than some markup used to capture API design details. You don’t need to be a software developer to take advantage of the process and techniques described in this book. It doesn’t dive into a specific programming language or prescribe a specific design or development methodology.

The scope of the full API design and delivery lifecycle is big. While there are some insights provided that extend beyond API design, it is impossible for me to capture every detail and situation that could occur. Instead, this book tackles the challenges teams encounter when going from an idea to business requirements and, ultimately, to an API design.

Let’s get started.