Continuous API Management, 2nd Edition (Mehdi Medjaoui, Erik Wilde, Ronnie Mitra etc.) (Z-Library)

📄 File Format: PDF

💾 File Size: 3.4 MB

📖 Read Online ⬇️ Download

Registered users can read the full content for free

Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.

📄 Page 1

(This page has no text content)

📄 Page 2

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

📄 Page 3

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

📄 Page 4

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

📄 Page 5

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

📄 Page 6

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-10352-1 [LSI]

📄 Page 7

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

📄 Page 8

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

📄 Page 9

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.

📄 Page 10

Kin Lane, The API Evangelist

📄 Page 11

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

📄 Page 12

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

📄 Page 13

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

📄 Page 14

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

📄 Page 15

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.

📄 Page 16

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 Please address comments and questions concerning this book to the publisher: O’Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472

📄 Page 17

800-998-9938 (in the United States or Canada) 707-829-0515 (international or local) 707-829-0104 (fax) We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at https://oreil.ly/cam-2e. Email bookquestions@oreilly.com to comment or ask technical questions about this book. For news and information about our books and courses, visit http://oreilly.com. Find us on Facebook: http://facebook.com/oreilly Follow us on Twitter: http://twitter.com/oreillymedia Watch us on YouTube: http://youtube.com/oreillymedia Acknowledgments Once again, we have many people to thank for all the help and support we received as we pulled together new material for this second edition. As usual, our first thanks goes to all the people we consulted with and had the privilege to interview, and all those who attended our workshops and online webinars. The feedback was great, and we learned something new with every encounter. Additional thanks goes to the folks at NGINX who encouraged us to revise this book and who helped sponsor the work. Special thanks goes to all those who read early drafts and helped us shape the final book you see before you. We’d also like to thank James Higginbotham, Hibri Marzook, Marjukka Niinioja, and Matthew Reinbold for all the time they took to read and review our work and point out ways we could make it better. And, of course, none of this would be possible without the support of the folks at O’Reilly Media. Our thanks go to Melissa Duffield, Gary

📄 Page 18

O’Brien, Kate Galloway, Kim Wimpsett, and many others who devoted their time and talent to helping us pull everything together.

📄 Page 19

Chapter 1. The Challenge and Promise of API Management Management is, above all, a practice where art, science, and craft meet. —Henry Mintzberg According to an IDC report from 2019, 75% of the companies surveyed expected to be “digitally transformed” in the next decade and expected that 90% of all new apps would feature microservice architecture powered by APIs. It was also noted that, for API-focused organizations, up to 30% of revenue was generated via digital channels. At the same time, these companies identified key barriers to API adoption as “complexity,” “security,” and “governance.” Finally, this was one of the key summary findings: “Defining the right app architecture requires a deep understanding of the challenges related to governing, managing and orchestrating these foundational technology components.” This survey, like the one from Coleman Parkes we cited in the first edition of this book, contains a mix of encouragement and caution. An interesting trend we have seen in the last few years is a widening gap between the “API haves” and “API have-nots.” For example, when asked the question “Does your company have an API management platform?” 72% of media and services companies answered “yes,” while only 46% of companies in the manufacturing sector replied in the affirmative. All indications are that APIs will continue to drive business growth going forward, and it is imperative that companies from all segments of the economy step up to the challenge of digital transformation. The good news is there are many companies out there successfully managing their API programs. The not-so-good news is that their experience and expertise is not easily shared or commonly available. There are several reasons for this. Most of the time, organizations that are doing 1 2 3

📄 Page 20

well in their API management programs are simply too busy to share their experiences with others. In a few cases, we’ve talked to companies that are very careful about how much of their API management expertise they share with the outside world; they are convinced API skills are a competitive advantage and are slow to make their findings public. Finally, even when companies share their experience at public conferences and through articles and blog posts, the information they share is usually company-specific and difficult to translate to a wide range of organizations’ API programs. This book is an attempt to tackle that last problem—translating company- specific examples into shared experience all organizations can use. To that end, we have visited with dozens of companies, interviewed many API technologists, and tried to find the common threads between the examples companies have shared with us and with the public. There are a small handful of themes that run through this book that we’ll share here in this introductory chapter. A key challenge to identify right up front is sorting out just what people mean when they talk about APIs. First, the term API can be applied to just the interface (e.g., an HTTP request URL and JSON response). It can also refer to the code and deployment elements needed to place an accessible service into production (e.g., the customerOnBoarding API). Finally, we sometimes use API to refer to a single instance of a running API (e.g., the customerOnBoarding API running in the AWS cloud versus the customerOnBoarding API running on the Azure cloud). Another important challenge in managing APIs is the difference between the work of designing, building, and releasing a single API and supporting and managing many APIs—what we call an API landscape. We will spend a good deal of time in this book on both ends of this spectrum. Concepts like API as a product (AaaP) and the skills needed to create and maintain APIs (what we call API pillars) are examples of dealing with the challenges of a single API. We will also talk about the role of API maturity models and the work of dealing with change over time as important aspects of managing an API.