Continuous API Management Making the Right Decisions in an Evolving Landscape, 2nd Edition (Mehdi Medjaoui, Erik Wilde, Ronnie Mitra etc.) (Z-Library)

NGINX

Praise for Continuous API Management Impressively, the authors have managed to make this a book about APIs in general, as opposed to being about specific technologies. Regardless of your API technology of choice, you’ll definitely get valuable guidance from this book. —Stefan Tilkov, CEO and principal consultant at INNOQ APIs are the fabric of the modern enterprise. This book will be your guide to implementing and managing a pervasive API landscape, covering architecture, team structure, and evolution. —Gregor Hohpe, author of The Software Architect Elevator Continuous API Management offers an excellent guide for those responsible for establishing and scaling their API program. From practical advice to deep dives into all aspects of delivering an API program, this is an essential resource for everyone from executives to API practitioners. —James Higginbotham, executive API consultant and author of Principles of Web API Design Copious print details the intimates of web API creation. However, the CAM book stands alone as a holistic guide through the API creation landscape. This reference is mandatory insight for technology leaders (and leaders-in-training). —Matthew Reinbold, author of the Net API Notes newsletter and director of API ecosystems and digital transformation at Postman Mike, Mehdi, Ronnie, and Erik created a far-reaching, insightful book that captures what is needed to create, evolve, and manage complex API systems that thrive in the connected world. —Hibri Marzook, principal consultant at Contino

Continuous API Management is the most comprehensive book out there when it comes to managing API products. It is full of practical guidance, and I have seen numerous organizations use its lessons to help advance their digital strategies using APIs. —Matt McLarty, global leader for API strategy at MuleSoft, a Salesforce company

Continuous API Management SECOND EDITION Making the Right Decisions in an Evolving Landscape Mehdi Medjaoui, Erik Wilde, Ronnie Mitra, and Mike Amundsen

Continuous API Management by Mehdi Medjaoui, Erik Wilde, Ronnie Mitra, and Mike Amundsen Copyright © 2022 Mehdi Medjaoui, Build Digital GmbH, Kudo & Leap Ltd., and 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 Development Editor: Gary O’Brien Production Editor: Kate Galloway Copyeditor: Kim Wimpsett Proofreader: Piper Editorial Consulting, LLC Indexer: Judith McConville Interior Designer: David Futato Cover Designer: Karen Montgomery Illustrator: Kate Dullea November 2018: First Edition October 2021: Second Edition

Revision History for the Second Edition 2021-10-18: First Release See http://oreilly.com/catalog/errata.csp?isbn=9781098103521 for release details. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Continuous API Management, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. The views expressed in this work are those of the authors, and do not represent the publisher’s views. While the publisher and the authors have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the authors 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. This work is part of a collaboration between O’Reilly and NGINX. See our statement of editorial independence. 978-1-098-10353-8 [LSI]

Dedication To those who coached me during the book writing, to my fellow partners who helped me to be useful in the industry, to Kin Lane who shared with me his passion for APIs, and to all the API practitioners who shared their API practices with me that inspired this book. To my parents. —Mehdi Medjaoui To all the people in my life who made this book possible. It’s been quite a ride! —Erik Wilde To Kairav, for helping me write this dedication. —Ronnie Mitra To all the companies that invited us to come share what we’ve learned and, in the process, taught us so much that we had to try to capture it in this book. —Mike Amundsen

Foreword from NGINX The API is now the connective tissue of the world’s technology fabric. There are tens of thousands of public and open APIs that deliver a huge range of functionality to web and mobile applications, from weather data to betting odds to flight arrival times to voice connectivity. The total API universe is many times that size when you factor in closed APIs used for gated services. Microservices and Kubernetes are contributing to the explosion of the API economy, as well; APIs are the default communication modality for cloud native applications. As organizations expand, they create and consume more APIs. This requires some thinking and planning for a future where almost everything is connected via API. In this future, what kind of guidelines should you provide for designing, implementing, and deploying APIs in your organization? And how can you design systems of governance and development to constantly scale the technology, people, processes, and policies for APIs? Continuous API Management provides insights into these critical questions. This book is a detailed yet accessible manual of best practices for technical practitioners, DevOps leaders, and any other professionals working on API business strategy. With rich examples and a clear point of view, the book provides guidance on all the critical business elements of planning, provisioning, delivering, and maintaining APIs —from inception to the evolution of API strategies as enterprises scale up quickly. The authors—Mehdi Medjaoui, Erik Wilde, Ronnie Mitra, and Mike Amundsen—give you access to insights gleaned from decades of experience in the real world. Their writing and ideas provide a rich guide to the holistic development of your API program, from ideation to realization to maturation. The authors are also practitioners, giving

readers insights into both the technical and business aspects of the process. You will learn from their experience with a front-row seat, observing and discussing common approaches to API management adopted by dozens of enterprises across multiple industries. NGINX is used to power numerous API management solutions, including Axway, Kong, MuleSoft, Red Hat 3scale, and Torry Harris. NGINX is also used as the technology foundation for branded API management product of several public clouds. Not surprisingly, NGINX is also the most popular solution for API management, with 40% of the market according to NGINX surveys. NGINX Controller’s API Management Module is a full API lifecycle management solution that is both lightweight and high performance. With a true distributed control plane / data plane architecture designed for low latency and nearly infinite scale, NGINX can handle the API needs of enterprises running both monolithic applications and modern distributed applications built with microservices. Whether you are just beginning your API journey for your enterprise or need to overhaul an existing API strategy, we hope this book will help you move along the path toward a stable and successful API program. Karthik Krishnaswamy Director, Product Marketing NGINX, Inc.

Foreword to the First Edition APIs are a journey for any company, organization, institution, or government agency learning to properly manage their digital resources across an ever-expanding and evolving competitive digital landscape. This digital transformation, which has been building over the last five years, is beginning to result in a shift across the API landscape, where companies are beginning to stop asking if they should be doing APIs and have begun seeking more knowledge on how to do APIs properly. Organizations are realizing that there’s more to APIs than just creating them; a lot goes into delivering APIs throughout the entire API lifecycle. The authors behind Continuous API Management possess a unique understanding of what it takes to move an API from ideation to realization consistently, at scale, and in a repeatable way—providing the makings for a pretty unique learning opportunity. Most API practitioners operate with a view of the API landscape spanning a single set of APIs. Medjaoui, Wilde, Mitra, and Amundsen, the authors of this book, possess a unique view of the API landscape at a 250,000-foot level, spanning thousands of APIs, multiple industries, and some of the largest enterprise organizations out there today. I can count the top-tier API talent that exists around the globe on both my hands, and Medjaoui, Wilde, Mitra, and Amundsen are always first to be counted on my right hand. These authors bring a wealth of experience to the table when it comes to understanding what you need to move APIs from inception to design, from development to production, and back again. There just isn’t another team of API experts out there who have the scope and the breadth of API knowledge that this team possesses, making this book destined to become that tattered O’Reilly tome that lives within reach on the corner of your desk—something you read again and again. I’ve read numerous books on the technical aspects of creating APIs, including books about hypermedia and everything you need to know

about REST and how to deliver on this vision in a variety of programming languages and platforms. This is the first API book that I’ve read that holistically approaches the delivery of APIs from start to finish, addressing not only the technological details but also the critical business elements of operating APIs—which also includes the critical human side of API education, realization, and activation across large enterprise organizations. The book methodically lays out the essential building blocks any enterprise API architect will need to deliver reliable, secure, and consistent APIs at scale; it will help any API team quantify their operations and think more critically about how APIs can be improved upon and evolved, while also establishing and refining a structured yet agile approach to delivering APIs in a standardized way across teams. After putting down this book, I felt I had a refreshed look at the modern API lifecycle—but more importantly, I was left with a wealth of ideas about how I actually quantify and measure my API operations, and the API lifecycle strategy I am using to manage my operations. Even with my knowledge of the space, this book forced me to look at the landscape in some important new ways. I walked away saturated with information that reinforced some of what I already knew, but also shifted and moved around some of what I thought I knew, forcing me to evolve in some of my existing practices. For me, this is what the API journey is all about: continually being challenged, learning, planning, executing, measuring, and repeating until you find the desired results. Continuous API Management reflects this reality of delivering APIs, providing us with a reusable guide to the technology, business, and politics of doing APIs at scale within the enterprise. Don’t just read this book once. Read it; then go out and execute on your vision. Evolve your API strategy, and define a version of the API lifecycle that is all your own, taking what you’ve learned from Medjaoui, Wilde, Mitra, and Amundsen and putting it to work. However, every once in a while, pick this book up again and give it

another read. I guarantee there will be little nuggets throughout the book that you’ll rediscover and see in a new light each time you work through it—something that will build and improve your understanding of what is happening across the API landscape and help you more confidently participate (or lead) when it comes to doing business with APIs across the expanding online economy. Kin Lane, The API Evangelist

Preface Welcome to the second edition of Continuous API Management. The opening paragraph for the previous edition, released in 2018, stated: As society and business have grown increasingly digital in nature, the demand for connected software has exploded. In turn, the application programming interface (API) has emerged as an important resource for modern organizations because it facilitates software connections. But managing these APIs effectively has proven to be a new challenge. Getting the best value from your APIs means learning how to manage their design, development, deployment, growth, quality, and security while dealing with the complicating factors of context, time, and scale. And, in the intervening years, not much has changed when it comes to the growth and challenges of API management. The good news is that, in the years since our first edition, more tooling, more training, and more experience has help grow and mature the API management space. The not-so-good news is that the authors still see lots of organizations struggling to meet the demands of connecting people, services, and companies using APIs. This new edition is our chance to provide updates on how companies are progressing, share some new success stories, and refine some of the material we first introduced in 2018. While we’ve added new examples and updated existing ones, we’ve still retained the same basic approach and outline for this new release. Hopefully these changes will help you extend your own journey on the road to continuous API management. Who Should Read This Book

If you are just starting to build an API program and want to understand the work ahead of you, or if you already have APIs but want to learn how to manage them better, then this is the book for you. In this book, we’ve tried to build an API management framework that can be applied to more than one context. In these pages you’ll find guidance that will help you to manage a single API that you want to share with developers around the world, as well as advice for building a complex set of APIs in a microservice architecture designed only for internal developers—and everything in between. We’ve also written this book to be as technologically neutral as possible. The advice and analysis we provide is applicable to any API-based architecture, including HyperText Transfer Protocol (HTTP), Create/Read/Update/Delete (CRUD), REpresentational State Transfer (REST), GraphQL, and event-driven styles of interaction. This is a book for anyone who wants to improve the decisions being made about their APIs. What’s in This Book This book contains our collective knowledge from many years spent designing, developing, and improving APIs—both our own and others’. We’ve distilled all that experience into this book. We’ve identified two core factors for effective API development: adopting a product perspective and implementing the right kind of team. We’ve also identified three essential factors for managing that work: governance, product maturity, and landscape design. These five elements of API management form a foundation on which you can build a successful API management program. In this book, we introduce each of these topics and provide you with guidance on how to shape them to fit your own organizational context.

The Outline We’ve organized the book so that the scope of management concerns grows as you progress through the chapters. We start by introducing the foundational concepts of decision-based governance and the API as a product. This is followed by a tour of all the work that must be managed when building an API product. From this simple view of a single API, we then add the aspect of time as we dive into what it means to change an API and how the maturity of the API impacts those change decisions. This is followed by an exploration of the teams and people who do that change work. Finally, in the last half of the book, we tackle the complexities of scale and the challenges of managing a landscape of API products. Here is a short summary of what you’ll find in each chapter: Chapter 1, “The Challenge and Promise of API Management” introduces the API management domain and explains why it’s so difficult to manage APIs effectively. Chapter 2, “API Governance” explores governance from the perspective of decision-based work—a foundational concept for API management. Chapter 3, “The API as a Product” establishes the API-as-a- product perspective and why it’s an essential part of any API strategy. Chapter 4, “The Pillars of an API Product” outlines the ten essential pillars of work in the API product domain. These pillars form a set of decision-making tasks that must be managed. Chapter 5, “Continuous API Improvement” provides insight into what it means to change an API continuously. It introduces the need to adopt a continuous change mentality

and provides an understanding of the different types of API changes (and their impacts) that you’ll encounter. Chapter 6, “API Styles” is a new chapter for this edition. It explores the five most common API styles we see as we visit with companies around the world and digs into the strengths and drawbacks of each style to help you select the ones appropriate for each use case you encounter. Chapter 7, “The API Product Lifecycle” introduces the API product lifecycle, a framework that will help you manage API work across the ten pillars over the life of an API product. Chapter 8, “API Teams” addresses the people element of an API management system by exploring the typical roles, responsibilities, and design patterns for an API team over the life of an API product. Chapter 9, “API Landscapes” adds the perspective of scale to the problem of managing APIs. It introduces the eight Vs —variety, vocabulary, volume, velocity, vulnerability, visibility, versioning, and volatility—that must be addressed when multiple APIs are changing at the same time. Chapter 10, “API Landscape Journey” outlines a continuous landscape design approach for managing API changes continuously and at scale. Chapter 11, “Managing the API Lifecycle in an Evolving Landscape” maps the landscape perspective back to the API-as-a-product perspective and identifies how API work changes when the landscape evolves around it. Chapter 12, “Continuing the Journey” ties together the story of API management that has emerged and provides advice on preparing for the future and starting your journey today.

What’s Not in This Book The scope of API management is big, and there is a massive amount of variation in contexts, platforms, and protocols. Given the constraints of time and space when writing a book, it was impossible for us to address all the specific implementation practices of API work. This book isn’t a guide for designing a REST API or for picking a security gateway product. If you are looking for a prescriptive guide to writing API code or designing an HTTP API, this isn’t the right book for you. While we do have examples that talk about specific practices, this isn’t an API implementation–focused book (the good news is there are plenty of books, blogs, and videos available already to help you fill that need). Instead, this book tackles a problem that is rarely addressed: how to effectively manage the work of building APIs within a complex, continuously changing organizational system. Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, and file extensions. Constant width Indicates program elements such as variable or function names, data types, statements, and keywords. Constant width italic Shows text that should be replaced with user-supplied values or by values determined by context.

TIP This element signifies a tip or suggestion. NOTE This element signifies a general note. WARNING This element indicates a warning or caution. O’Reilly Online Learning NOTE For more than 40 years, O’Reilly Media has provided technology and business training, knowledge, and insight to help companies succeed. Our unique network of experts and innovators share their knowledge and expertise through books, articles, and our online learning platform. O’Reilly’s online learning platform gives you on-demand access to live training courses, in-depth learning paths, interactive coding environments, and a vast collection of text and video from O’Reilly and 200+ other publishers. For more information, visit http://oreilly.com. How to Contact Us