WEB DEVELOPMENT/API Lauret The Design of Web APIs See first page Arnaud Lauret 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, mastering API design is a superskill It will make your web-facing services easier to consume and your clients—internal and external—happier Assembles the fundamental “building blocks of design 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-first mindset It teaches effective practices using numerous interesting examples —From the Foreword by Kin Lane ● ● ● ● 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 ” “ Answers nagging and complicated questions with a simple philosophy, but never tries to hide anything from you A fantastic introduction to the field ” —Bridger Howell, SoFi.com excellent guidebook “forAnestablishing a path to ful s ” REST 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 Handyman 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 API —Shawn Smith Penn State University Combines real-world “examples with difficult abstract ideas ” —Shayn Cornwell XeroOne Systems The Design of Web APIs What’s Inside API in an easy-to-access way, and walks you through the vast landscape in a friendly and comfortable manner Arnaud Lauret Foreword by Kin Lane ISBN-13: 978-1-61729-510-2 ISBN-10: 1-61729-510-8 MANNING $44.99 / Can $59.99 [INCLUDING eBOOK] MANNING MANNING www.EBooksWorld.ir API design topics inside the book Topic Page number Section What is a Web API? 1.1.1 What is a private or public API? 1.1.2 What is developer experience (DX)? 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 :KDWLVWKH2SHQ$3,6SHFLÀFDWLRQ" 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 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 API designers 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 +RZWRKDQGOHLPSOHPHQWDWLRQLQÁXHQFHRQ$3,GHVLJQ 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 6SHFLÀFDWLRQ 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 www.EBooksWorld.ir The Design of Web APIs ARNAUD LAURET Foreword by Kin Lane MANNING Shelter Island www.EBooksWorld.ir 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 Development editor: Technical development editor: Review editor: Production editor: Copy editor: Proofreader: Technical proofreader: Typesetter: Cover designer: ISBN 9781617295102 Printed in the United States of America www.EBooksWorld.ir Jenny Stout Michael Lund Ivan Martinovic´ Deirdre Hiam Frances Buran Melody Dolab Paul Grebenc Happenstance Type-O-Rama Marija Tudor brief contents Part Fundamentals of API design 1 ■ ■ ■ ■ What is API design? Designing an API for its users 17 Designing a programming interface 43 Describing an API with an API description format 77 Part Usable API design 109 ■ ■ ■ Designing a straightforward API 111 Designing a predictable API 137 Designing a concise and well-organized API 162 Part Contextual API design 181 10 11 12 13 ■ ■ ■ ■ ■ ■ Designing a secure API 183 Evolving an API design 213 Designing a network‑effcient API 246 Designing an API in context 275 Documenting an API 306 Growing APIs 334 iii www.EBooksWorld.ir contents foreword xi preface xiii acknowledgments xv about this book xvii about the author xxi about the cover illustration xxii Part Fundamentals of API design .1 What is API design? 1.1 What is an API? An API is a web interface for software 4 APIs turn software into LEGO® bricks ■ 1.2 Why API design matters 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 ■ v vi contents 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 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 ■ ■ ■ ■ 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 ■ vii contents 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 ■ 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 Usable API design 109 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 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 ■ 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 Contextual API design 181 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 ■ ... this book is available for download from the publisher’s website at https://www.manning.com/books /the-design-of-web-apis liveBook discussion forum Purchase of The Design of Web APIs includes free