The Design of Web APIs (Arnaud Lauret) (Z Library)

Arnaud Lauret ISBN-13: 978-1-61729-510-2 ISBN-10: 1-61729-510-8 A n API frees developers to integrate with an application without knowing its code-level details. Whether you’re using established standards like REST and OpenAPI or more recent approaches like GraphQL or gRPC, master- ing API design is a superskill. It will make your web-facing services easier to consume and your clients—internal and external—happier. Drawing on author Arnaud Lauret’s many years of API design experience, this book teaches you how to gather requirements, how to balance business and technical goals, and how to adopt a consumer-fi rst mindset. It teaches effective practices using numerous interesting examples. What’s Inside ● Characteristics of a well-designed API ● User-oriented and real-world APIs ● Secure APIs by design ● Evolving, documenting, and reviewing API designs Written for developers with minimal experience building and consuming APIs. A software architect with extensive experience in the banking industry, Arnaud Lauret has spent 10 years using, designing, and building APIs. He blogs under the name of API Handy- man and has created the API Stylebook website. To download their free eBook in PDF, ePub, and Kindle formats, owners of this book should visit www.manning.com/books/the-design-of-web-apis $44.99 / Can $59.99 [INCLUDING eBOOK] The Design of Web APIs WEB DEVELOPMENT/API Lauret M A N N I N G The Design of W eb APIs MANN I N G “Assembles the fundamental building blocks of API design in an easy-to-access way, and walks you through the vast landscape in a friendly and comfortable manner.” —From the Foreword by Kin Lane “Answers nagging and complicated questions with a simple philosophy, but never tries to hide anything from you. A fantastic introduction to the fi eld.”—Bridger Howell, SoFi.com “An excellent guidebook for establishing a path to RESTful APIs.”—Shawn Smith Penn State University “Combines real-world examples with diffi cult abstract ideas.”—Shayn Cornwell XeroOne Systems M A N N I N G See first page Arnaud Lauret Foreword by Kin Lane

API design topics inside the book Topic Page number Section What is a Web API? 4 1.1.1 What is a private or public API? 6 1.1.2 What is developer experience (DX)? 9 1.2.1 What is an implementation? 21 2.2.1 What is a REST API? 45 3.1.1 What is the HTTP protocol? 47 3.1.2 What is the REST architectural style? 72 3.5.1 79 4.1.1 What is JSON Schema? 91 4.3 What is API security? 185 8.1 What is API versioning? 229 9.2 What is a breaking change? 213 9 What are common web API network concerns? 247 10.1 What are the different types of APIs? 277, 299 11.1, 11.3 What are the different types of API documentation? 306 12 What do API designers do on API projects? 335 13.1 How to identify functional API goals 24, 41, 176, 207, 343 2.3, 2.4.5, 7.2.2, 8.4.2, 13.3.1 How to design data 62, 112, 139, 164, 175, 203, 240 3.3.1, 5.1, 6.1.1, 7.1.1, 7.2.1, 8.4.1, 9.3.1 How to design goal parameters 66, 119, 141, 203, 211 3.3.3, 5.2.1, 6.1.2, 8.4.1, 8.4.4 How to design goal success responses 65, 128, 141, 156, 157, 167, 203, 211 3.3.2, 5.2.5, 6.1.2, 6.3.1, 6.3.2, 7.1.2, 8.4.1, 10.3 How to design goal error responses 122, 126, 167, 209, 243 5.2.3, 5.2.4, 7.1.2, 8.4.3, 9.3.2 How to optimize goals 129, 147, 175, 244, 264 5.3, 6.2, 7.2.1, 9.3.3, 10.3.3 34, 277, 292 2.4, 11.1, 11.2 How to modify an existing API 215 9.1 How to choose resource paths 54, 139, 201, 211 3.2.3, 6.1.1, 8.3.2, 8.4.4 How to choose HTTP methods to represent actions on resources 56, 160 3.2.4, 6.3.3 How to choose HTTP status codes 122, 167, 209 5.2.3, 7.1.2, 8.4.3 How to optimize network communication with HTTP 254 10.2 How to describe API goals with the OpenAPI 85, 168, 313 4.2, 7.1.3, 12.1.2 How to describe data with JSON Schema and OAS 94, 310 4.3.2, 12.1.1 How to reuse components in an OAS document 102 4.4 How to describe API security with OAS 198, 320 8.2.4, 12.1.3

MANN I NG SHELTER ISLAND The Design of Web APIs ARNAUD LAURET Foreword by Kin Lane

For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact Special Sales Department Manning Publications Co. 20 Baldwin Road PO Box 761 Shelter Island, NY 11964 Email: orders@manning.com ©2019 by Manning Publications Co. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps. Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books we publish printed on acid- free paper, and we exert our best efforts to that end. Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine. ∞ Manning Publications Co. 20 Baldwin Road PO Box 761 Shelter Island, NY 11964 ISBN 9781617295102 Printed in the United States of America Development editor: Jenny Stout Technical development editor: Michael Lund Review editor: Ivan Martinović Production editor: Deirdre Hiam Copy editor: Frances Buran Proofreader: Melody Dolab Technical proofreader: Paul Grebenc Typesetter: Happenstance Type-O-Rama Cover designer: Marija Tudor

iii brief contents Part 1 Fundamentals of API design ....................................... 1 1 ■ What is API design? 3 2 ■ Designing an API for its users 17 3 ■ Designing a programming interface 43 4 ■ Describing an API with an API description format 77 Part 2 Usable API design .....................................................109 5 ■ Designing a straightforward API 111 6 ■ Designing a predictable API 137 7 ■ Designing a concise and well-organized API 162 Part 3 Contextual API design ............................................181 8 ■ Designing a secure API 183 9 ■ Evolving an API design 213 10 ■ Designing a network-effcient API 246 11 ■ Designing an API in context 275 12 ■ Documenting an API 306 13 ■ Growing APIs 334

v contents foreword xi preface xiii acknowledgments xv about this book xvii about the author xxi about the cover illustration xxii Part 1 Fundamentals of API design ........................1 1 What is API design? 3 1.1 What is an API? 4 An API is a web interface for software 4 ■ APIs turn software into LEGO® bricks 6 1.2 Why API design matters 9 A public or private API is an interface for other developers 9 ■ An API is made to hide the implementation 10 ■ The terrible consequences of poorly designed APIs 11 1.3 The elements of API design 14 Learning the principles beyond programming interface design 14 ■ Exploring all facets of API design 15

vi CONTENTS 2 Designing an API for its users 17 2.1 The right perspective for designing everyday user interfaces 18 Focusing on how things work leads to complicated interfaces 18 ■ Focusing on what users can do leads to simple interfaces 20 2.2 Designing software’s interfaces 21 Viewing an API as software’s control panel 21 ■ Focusing on the consumer’s perspective to create simple APIs 22 2.3 Identifying an API’s goals 24 Identifying the whats and the hows 25 ■ Identifying inputs and outputs 27 ■ Identifying missing goals 28 ■ Identifying all users 31 ■ Using the API goals canvas 32 2.4 Avoiding the provider’s perspective when designing APIs 34 Avoiding data infuences 35 ■ Avoiding code and business logic infuences 36 ■ Avoiding software architecture infuences 38 ■ Avoiding human organization infuences 40 ■ Detecting the provider’s perspective in the API goals canvas 41 3 Designing a programming interface 43 3.1 Introducing REST APIs 45 Analyzing a REST API call 45 ■ Basic principles of HTTP 47 ■ Basic principles of REST APIs 48 3.2 Transposing API goals into a REST API 49 Identifying resources and their relationships with the API goals canvas 49 ■ Identifying actions and their parameters and returns with the API goals canvas 52 ■ Representing resources with paths 54 ■ Representing actions with HTTP 56 ■ REST API and HTTP cheat sheet 60 3.3 Designing the API’s data 62 Designing concepts 62 ■ Designing responses from concepts 65 ■ Designing parameters from concepts or responses 66 ■ Checking parameter data sources 67 ■ Designing other parameters 68 3.4 Striking a balance when facing design challenges 69 REST trade-off examples 69 ■ Balancing user-friendliness and compliance 71

viiCONTENTS 3.5 Understanding why REST matters for the design of any API 71 Introducing the REST architectural style 72 ■ The impact of REST constraints on API design 74 4 Describing an API with an API description format 77 4.1 What is an API description format? 78 Introducing the OpenAPI Specifcation (OAS) 79 ■ Why use an API description format? 81 ■ When to use an API description format 84 4.2 Describing API resources and actions with OAS 85 Creating an OAS document 85 ■ Describing a resource 86 ■ Describing operations on a resource 87 4.3 Describing API data with OpenAPI and JSON Schema 91 Describing query parameters 92 ■ Describing data with JSON Schema 94 ■ Describing responses 97 ■ Describing body parameters 100 4.4 Describing an API effciently with OAS 102 Reusing components 102 ■ Describing path parameters 105 Part 2 Usable API design ..................................... 109 5 Designing a straightforward API 111 5.1 Designing straightforward representations 112 Choosing crystal-clear names 113 ■ Choosing easy-to-use data types and formats 115 ■ Choosing ready-to-use data 116 5.2 Designing straightforward interactions 118 Requesting straightforward inputs 119 ■ Identifying all possible error feedbacks 121 ■ Returning informative error feedback 122 ■ Returning exhaustive error feedback 126 ■ Returning informative success feedback 128 5.3 Designing straightforward fows 129 Building a straightforward goal chain 131 ■ Preventing errors 132 ■ Aggregating goals 134 ■ Designing stateless fows 135

viii CONTENTS 6 Designing a predictable API 137 6.1 Being consistent 138 Designing consistent data 139 ■ Designing consistent goals 141 ■ The four levels of consistency 142 ■ Copying others: Following common practices and meeting standards 143 ■ Being consistent is hard and must be done wisely 146 6.2 Being adaptable 147 Providing and accepting different formats 147 Internationalizing and localizing 151 ■ Filtering, paginating, and sorting 153 6.3 Being discoverable 155 Providing metadata 156 ■ Creating hypermedia APIs 157 Taking advantage of the HTTP protocol 160 7 Designing a concise and well-organized API 162 7.1 Organizing an API 163 Organizing data 164 ■ Organizing feedback 167 ■ Organizing goals 168 7.2 Sizing an API 174 Choosing data granularity 175 ■ Choosing goal granularity 176 ■ Choosing API granularity 178 Part 3 Contextual API design ............................. 181 8 Designing a secure API 183 8.1 An overview of API security 185 Registering a consumer 185 ■ Getting credentials to consume the API 186 ■ Making an API call 188 ■ Envisioning API design from the perspective of security 189 8.2 Partitioning an API to facilitate access control 191 Defning fexible but complex fne-grained scopes 192 ■ Defning simple but less fexible coarse-grained scopes 195 ■ Choosing scope strategies 197 ■ Defning scopes with the API description format 198 8.3 Designing with access control in mind 200 Knowing what data is needed to control access 200 ■ Adapting the design when necessary 201

ixCONTENTS 8.4 Handling sensitive material 203 Handling sensitive data 203 ■ Handling sensitive goals 207 ■ Designing secure error feedback 209 ■ Identifying architecture and protocol issues 211 9 Evolving an API design 213 9.1 Designing API evolutions 215 Avoiding breaking changes in output data 215 ■ Avoiding breaking changes to input data and parameters 220 ■ Avoiding breaking changes in success and error feedback 223 ■ Avoiding breaking changes to goals and fows 225 ■ Avoiding security breaches and breaking changes 226 ■ Being aware of the invisible interface contract 228 ■ Introducing a breaking change is not always a problem 229 9.2 Versioning an API 229 Contrasting API and implementation versioning 230 ■ Choosing an API versioning representation from the consumer’s perspective 232 ■ Choosing API versioning granularity 234 Understanding the impact of API versioning beyond design 238 9.3 Designing APIs with extensibility in mind 239 Designing extensible data 240 ■ Designing extensible interactions 243 ■ Designing extensible fows 244 ■ Designing extensible APIs 245 10 Designing a network-effcient API 246 10.1 Overview of network communication concerns 247 Setting the scene 248 ■ Analyzing the problems 250 10.2 Ensuring network communication effciency at the protocol level 254 Activating compression and persistent connections 254 ■ Enabling caching and conditional requests 255 ■ Choosing cache policies 258 10.3 Ensuring network communication effciency at the design level 259 Enabling fltering 260 ■ Choosing relevant data for list representations 262 ■ Aggregating data 264 ■ Proposing different representations 266 ■ Enabling expansion 268 ■ Enabling querying 269 ■ Providing more relevant data and goals 271 ■ Creating different API layers 273

x CONTENTS 11 Designing an API in context 275 11.1 Adapting communication to the goals and nature of the data 277 Managing long processes 277 ■ Notifying consumers of events 279 ■ Streaming event fows 281 ■ Processing multiple elements 286 11.2 Observing the full context 292 Being aware of consumers' existing practices and limitations 292 Carefully considering the provider’s limitations 296 11.3 Choosing an API style according to the context 299 Contrasting resource-, data-, and function-based APIs 300 Thinking beyond request/response- and HTTP-based APIs 305 12 Documenting an API 306 12.1 Creating reference documentation 308 Documenting data models 310 ■ Documenting goals 313 Documenting security 320 ■ Providing an overview of the API 321 ■ Generating documentation from the implementation: pros and cons 322 12.2 Creating a user guide 323 Documenting use cases 324 ■ Documenting security 326 Providing an overview of common behaviors and principles 327 Thinking beyond static documentation 327 12.3 Providing adequate information to implementers 327 12.4 Documenting evolutions and retirement 330 13 Growing APIs 334 13.1 The API lifecycle 335 13.2 Building API design guidelines 336 What to put in API design guidelines 337 ■ Continuously building guidelines 340 13.3 Reviewing APIs 342 Challenging and analyzing needs 343 ■ Linting the design 346 ■ Reviewing the design from the provider’s perspective 348 ■ Reviewing the design from the consumer’s perspective 350 ■ Verifying the implementation 350 13.4 Communicating and sharing 353 index 355

xi foreword For over a decade, API design has always meant REST to most developers. This real- ity has been constructed through regular waves of books and API-centered blogs that push RESTful design belief systems, leaving the discipline very focused and often times dogmatic. The Design of Web APIs by Arnaud Lauret is the beginning wave of the next generation of API design guidance, which will help us transcend this reality that has held us back for over a decade. His pragmatic approach to API design is still rooted in REST, but he has worked hard to bring real world API design knowledge to the table— minus the usual dogma. Lauret takes us through the fundamentals of API design that you can easily fnd in other industry books, but he assembles the fundamental building blocks of this disci- pline in a very easy-to-access way and walks you through the vast landscape in a friendly and comfortable manner. I have known Arnaud personally for several years and consider him among a handful of top tier API talent that don’t just understand how you do APIs technically, but also understand the human-centered challenges of delivering APIs and how APIs can positively or negatively impact your API experience among developers. Arnaud focuses his knowledge on not just the act of designing an API, but also the act of providing a well-designed API for your intended audience in a thoughtful way. I have personally watched Arnaud sit in the front row of hundreds of API talks around the globe, absorbing the best-of-breed API wisdom. One just needs to visit his Twitter timeline or to follow the hashtag for a popular API event to understand what I am talking about. He has a unique approach to listening to API industry speakers, processing the API information they are sharing, while also live-tweeting the most important points of the talk as a steady stream of API insights. It makes me happy to see Arnaud take this accumulated knowledge and put it down in book form, continuing his

xii FOREWORD approach to not just sharpening his own skills, but also making sure he is sharing what he knows and his unique approach to API design with the world. Arnaud is a rare breed of API analyst that listens, cares, understands, and distills API knowledge down into usable building blocks you can actually put to work in your business world. After the API design world began to pick up momentum after 2012 and the OpenAPI (FKA Swagger) began to grow in dominance, Arnaud was one of just a handful of API experts who worked hard to understand the potential of this specifcation, while also developing innovative tooling and visualizations around the open source API specif- cation standard. Doing the hard work to understand not just the specifcation, but how it can embody, represent, and even govern many of the API design principles you need to be successful in the space. It takes a lot of work to reach the point where you realize OpenAPI isn't just about documentation, a journey that most API developers end up not taking. Arnaud understands that OpenAPI isn't just about API documentation, but is the fundamental underpinning of API design for any platform—something that will help defne every other stop along your API lifecycle. The Design of Web APIs is the frst API design book I have seen that merges API design and OpenAPI together in such a thoughtful and pragmatic way, which is sure to help many developers along in their API journey. Spend the time to understand what Arnaud is sharing with you here. This isn't a skimming book. This isn't a one-read book. This is a handbook. This is your guide to taking the design of your APIs to the next level. It brings that loose bucket of API con- cepts you are familiar with and provides you with the blueprints to build the Millen- nium Falcon or even the Death Star (if you so choose) from your bucket of API Lego building blocks. I recommend reading this book, then putting it down for a month. Then get to work building an API and moving it from design to actually being deployed and publicly available—sharing it with a handful of developers. Then while you wait for feedback, sit down and read the book again. You will begin to understand the depth of what you hold in your hands and the value of the knowledge Arnaud is sharing with you. Then repeat this process until you are satisfed with your ability to design not a perfect API, but exactly the API you need to reach the consumers you are looking to make an impact upon. —Kin Lane, The API Evangelist

xiii preface For most of my career, I have worked on connecting software bricks together using vari- ous software interface technologies, from simple fles and databases to remote software interfaces based on RPC, Corba, Java RMI, SOAP web services, and web APIs. Through- out these years, I have been fortunate to work on motley distributed systems, mixing very old mainframe technology with state-of-the art cloud systems and everything in between. I also have been fortunate to work on both sides of software interfaces in various contexts. I worked on IVR (Interactive Voice Response), websites, and mobile applications built on top of huge service-oriented architecture systems. I’ve built both private and public web services and web APIs for frontend and backend applications. During all these years, I complained a lot about the terrible software interfaces, and I fell into many traps and created terrible software interfaces too. As years passed, and technology evolved from RPC to SOAP web services and web APIs, connecting software together became more and more simple from a technical point of view. But whatever the technology used, I have learned that a software interface is far more than technical plumbing or a by-product of a software project. After attending my frst API conferences in 2014, “API Days” in Paris, I realized that many other people were struggling with APIs just like me. That is why in 2015 I started my API Handyman blog and also started to participate in API conferences. I wanted to share my experiences with others and help them to avoid falling in the same traps I had fallen into. Writing and speaking about web APIs not only allowed me to help others, it also allowed me to learn even more about them. After two years of blogging and speaking at conferences, the idea of writing a book came. I wanted to write a book for my old self who fell into so many traps. As luck would have it, Manning Publications was looking for someone willing to write a book

xiv PREFACE about the OpenAPI Specifcation, an API description format (we’ll talk about it in chapter 4, by the way). I took a chance and proposed my Design of Everyday APIs book, and it was accepted. This title was inspired by Don Norman’s Design of Everyday Things (MIT Press, 1998), which is a book about design (you defnitely should read it). My idea was later replaced by the more straightforward The Design of Web APIs. I have to admit that I am more comfortable with this title; I don’t feel I’m borrowing from the fame of Don Norman anymore. In the beginning, the book’s content included the design of everyday things + API + REST vs. gRPC vs. GraphQL. It would have been quite indigestible, but I wanted to make a book whose principles could be used for any type of API. Month after month, the content was refned and enhanced to what is now The Design of Web APIs. I chose to focus on REST APIs and use those as a support example for you to learn web/remote API design principles, which would go beyond merely designing APIs. I think my old self would have been quite happy to read this book; I hope you like it too!

xv acknowledgments Two years. It took me two years to fnish this book. That’s a very long time, but that is what helped me to make it a great book that I hope you will like. I was not alone while working on it. There are a few people I’d like to thank for helping me during this jour- ney, and I also want to thank the people who made this journey possible. First and foremost, I want to thank my wife, Cinzia, and my daughter, Elisabetta. Thank you so much for your support and your patience while I was spending my eve- nings and weekends on “the book.” I love you so much. Next, I would like to thank everyone at Manning Publications. You can’t imagine how many people work on a book when you haven’t written one yet, and every one of one them has done a wonderful job. I would like to especially thank my editor, Mike Stephens, who believed in the book. Very special thanks also to my two development editors, Kevin Harreld and Jennifer Stout, and my technical development editor, Michael Lund. You really helped me a lot! This book wouldn’t have been the same without the three of you. And very special merci beaucoup to my ESL copyeditor, Rachel Head, who really, really, really has done an awesome job fxing my frenglish. Thank you to my production editor Deirdre Hiam, my copyeditor Frances Buran, proofreader Melody Dolab, and technical proofreader Paul Grebenc. I would also like to thank all the reviewers: Andrew Gwozdziewycz, Andy Kirsch, Bridger Howell, Edwin Kwok, Enrico Mazzarella, Mohammad Ali Bazzi, Narayanan Jayaratchagan, Peter Paul Sel- lars, Raveesh Sharma, Sanjeev Kumar Jaiswal, Sergio Pacheco, Shaun Hickson, Shawn Smith, Shayn Cornwell, Vincent Theron, and William Rudenmalm. A special thanks to Ivan Goncharov, who on March 15, 2017, forwarded me an email from Manning Publications, looking for someone to write a book that later became The Design of Web APIs. As luck would have it, I’m glad we met at REST Fest 2015.

xvi ACKNOWLEDGMENTS Thank you to all the people who took time to read the manuscript at various stages and provided invaluable encouragement and feedback. Special thanks to Isabelle Reusa and Mehdi Medjaoui for feld-testing the book’s content and providing their feedback. And thanks to all the API practitioners I have met and worked with over the years; I have put everything I have learned from you in this book. And fnally, a very big thanks to Mike Amundsen, Kin Lane, and Mehdi Medjaoui (again) for their encouragement and help when I started the API Handyman blog in 2015. This book wouldn’t have existed without you.

xvii about this book The Design of Web APIs was written to help you design web APIs that do more than just cover expressed needs. This book will help you design outstanding web APIs that are usable by anyone in many different contexts, and those that are also secure, durable, evolvable, effcient, and implementable. It uncovers all aspects of web API design and gives a full overview of the web APIs ecosystem and how API designers can contribute to it. Who should read this book The Design of Web APIs is, obviously, for anyone who needs to design web APIs. They can be developers working on a backend for mobile applications or websites or needing to connect microservices together, or they can be product owners working on an API as a product, and everything in between. Actually, this book can be read by all people working on a project involving the creation of an API. How this book is organized: a roadmap This book has three parts that cover 13 chapters. Part 1 teaches the most fundamental concepts and skills needed to design APIs. Chapter 1 discusses what an API is, why its design matters, and what the elements of API design are. Chapter 2 explains how to accurately determine an API’s purpose— its real goals— by focusing on the point of view of API users and the software consuming the API, and by avoiding the point of view of the organization and software exposing the API. Chapter 3 introduces the HTTP protocol, REST APIs, and the REST architectural style. It teaches how to design a web programming interface (comprising resources, actions on resources, data, parameters, and responses) based on the identifed goals.

xviii ABOUT THIS BOOK Chapter 4 introduces the OpenAPI Specifcation and demonstrates how to describe an API in a structured and standard way using such an API description format. Part 2 focuses on how to design don’t make me think APIs that will be easy to under- stand and easy to use. Chapter 5 explains how to design straightforward data representations, error and success feedback, and fows of API calls that people will understand instantly and use easily. Chapter 6 teaches how to design even more easy-to-understand and easy-to-use APIs, whose users (humans or machines) will be able to guess how APIs work, by making them consistent, adaptable, and discoverable. Chapter 7 shows how to organize and size all aspects of APIs in order to keep them easy to understand and easy to use. Part 3 shows that API designers must take into account the whole context surround- ing an API and the whole context surrounding the API design process itself. Chapter 8 describes API security and how to design secure APIs. Chapter 9 teaches how to modify an API without unduly impacting its users, and when and how to version it. It also demonstrates how to design APIs that will be easy to evolve from the ground up. Chapter 10 focuses on how to design network-effcient web APIs. Chapter 11 exposes the whole context that API designers must take into account when designing APIs. It comprises adapting communication mechanisms (request/ responses, asynchronous, events, and batch or bulk processing), evaluating and adapting to consumers' or providers' limitations, and choosing an adequate API style (resource-, function- or data-based). Chapter 12 explains how API designers participate in the creation of different types of API documentation, taking advantage of an API description format like the OpenAPI Specifcation. Chapter 13 shows how API designers can participate in the growing of many APIs by participating along the whole API lifecycle and across many APIs. It especially focuses on API design guidelines and API reviews. This book should be read from cover to cover, each chapter in order. Each new chap- ter expands what has been learned in previous ones. That being said, once you have fn- ished chapters 1, 2, and 3, you can jump to any chapter covering a topic that you need to investigate urgently. About the code This book contains many examples of source code both in numbered listings and in line with normal text. In both cases, source code is formatted in a fixed-width font like this to separate it from ordinary text. Sometimes code is also in bold to high- light code that has changed from previous steps in the chapter, such as when a new feature adds to an existing line of code.