Statistics
81
Views
0
Downloads
0
Donations
Author：JJ Geewax
API Design Patterns lays out a set of design principles for building internal and public-facing APIs. Summary A collection of best practices and design standards for web and internal APIs. In API Design Patterns you will learn: Guiding principles for API patterns Fundamentals of resource layout and naming Handling data types for any programming language Standard methods that ensure predictability Field masks for targeted partial updates Authentication and validation methods for secure APIs Collective operations for moving, managing, and deleting data Advanced patterns for special interactions and data transformations API Design Patterns reveals best practices for building stable, user-friendly APIs. These design patterns can be applied to solve common API problems and flexibly altered to fit your specific needs. Hands-on examples and relevant use-cases illustrate patterns for API fundamentals, advanced functionalities, and even uncommon scenarios. About the technology APIs are contracts that define how applications, services, and components communicate. API design patterns provide a shared set of best practices, specifications and standards that ensure APIs are reliable and simple for other developers to use. This book collects and explains the most important patterns from both the API design community and the experts at Google. About the book API Design Patterns lays out a set of design principles for building internal and public-facing APIs. Google API expert JJ Geewax presents patterns that ensure your APIs are consistent, scalable, and flexible. You'll improve the design of the most common APIs, plus discover techniques for tricky edge cases. Precise illustrations, relevant examples, and detailed scenarios make every pattern clear and easy to understand. What's inside Guiding principles for API patterns Fundamentals of resource layout and naming Advanced patterns for special interactions and data transformations A detailed case-study on building an API and addin
Tags
Support Statistics
¥.00 ·
0times
Text Preview (First 20 pages)
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
M A N N I N G JJ Geewax Foreword by Jon Skeet
Page
2
Topic This topic covers... Resource identification How to identify resources in an API Standard methods The set of standard methods for use in resource-oriented APIs Partial updates and retrievals How to interact with portions of resources Custom methods Using custom (non-standard) methods in resource-oriented APIs Long-running operations How to handle methods that are not instantaneous Rerunnable jobs Running repeated custom functionality in an API Singleton sub-resources Isolating portions of resource data Cross references How to reference other resources in an API Association resources How to manage many-to-many relationships with metadata Add and remove custom methods How to manage many-to-many relationships without metadata Polymorphism Designing resources with dynamically-typed attributes Copy and move Duplicating and relocating resources in an API Batch operations Extending methods to apply to groups of resources atomically Criteria-based deletion Deleting multiple resources based on a set of filter criteria Anonymous writes Ingesting unaddressable data into an API Pagination Consuming large amounts of data in bite-sized chunks Filtering Limiting result sets according to a user-specified filter Importing and exporting Moving data into or out of an API by interacting directly with a storage system Versioning and compatibility Defining compatibility and strategies for versioning APIs Soft deletion Moving resources to the “API recycle bin” Request deduplication Preventing duplicate work due to network interruptions in APIs Request validation Allowing API methods to be called in “safe mode” Resource revisions Tracking resource change history Request retrial Algorithms for safely retrying API requests Request authentication Verifying that requests are authentic and untampered with
Page
3
API Design Patterns
Page
4
(This page has no text content)
Page
5
API Design Patterns JJ GEEWAX FOREWORD BY JON SKEET MANN I NG SHELTER ISLAND
Page
6
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 ©2021 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. Development editor: Christina Taylor Technical development editor: Al Krinker Manning Publications Co. Review editor: Ivan Martinović 20 Baldwin Road Production editor: Deirdre S. Hiam PO Box 761 Copy editor: Michele Mitchell Shelter Island, NY 11964 Proofreader: Keri Hales Technical proofreader: Karsten Strøbæk Typesetter: Dennis Dalinnik Cover designer: Marija Tudor ISBN: 9781617295850 Printed in the United States of America
Page
7
To Kai and Luca. You are awesome.
Page
8
(This page has no text content)
Page
9
brief contents PART 1 INTRODUCTION ............................................................1 1 ■ Introduction to APIs 3 2 ■ Introduction to API design patterns 14 PART 2 DESIGN PRINCIPLES.....................................................31 3 ■ Naming 33 4 ■ Resource scope and hierarchy 47 5 ■ Data types and defaults 65 PART 3 FUNDAMENTALS ..........................................................85 6 ■ Resource identification 87 7 ■ Standard methods 104 8 ■ Partial updates and retrievals 122 9 ■ Custom methods 141 10 ■ Long-running operations 154 11 ■ Rerunnable jobs 175vii
Page
10
BRIEF CONTENTSviiiPART 4 RESOURCE RELATIONSHIPS ........................................187 12 ■ Singleton sub-resources 189 13 ■ Cross references 200 14 ■ Association resources 207 15 ■ Add and remove custom methods 218 16 ■ Polymorphism 225 PART 5 COLLECTIVE OPERATIONS..........................................237 17 ■ Copy and move 239 18 ■ Batch operations 254 19 ■ Criteria-based deletion 270 20 ■ Anonymous writes 278 21 ■ Pagination 285 22 ■ Filtering 299 23 ■ Importing and exporting 313 PART 6 SAFETY AND SECURITY ...............................................333 24 ■ Versioning and compatibility 335 25 ■ Soft deletion 357 26 ■ Request deduplication 371 27 ■ Request validation 383 28 ■ Resource revisions 390 29 ■ Request retrial 405 30 ■ Request authentication 416
Page
11
contents foreword xxi preface xxiii acknowledgments xxv about this book xxvii about the author xxxiii about the cover illustration xxxiv PART 1 INTRODUCTION ..................................................1 1 Introduction to APIs 3 1.1 What are web APIs? 3 1.2 Why do APIs matter? 5 1.3 What are resource-oriented APIs? 6 1.4 What makes an API “good”? 8 Operational 9 ■ Expressive 9 ■ Simple 10 ■ Predictable 12 2 Introduction to API design patterns 14 2.1 What are API design patterns? 14 2.2 Why are API design patterns important? 17ix
Page
12
CONTENTSx2.3 Anatomy of an API design pattern 19 Name and synopsis 19 ■ Motivation 19 ■ Overview 20 Implementation 21 ■ Trade-offs 21 2.4 Case study: Twapi, a Twitter-like API 22 Overview 22 ■ Listing messages 23 ■ Exporting data 26 PART 2 DESIGN PRINCIPLES ...........................................31 3 Naming 33 3.1 Why do names matter? 34 3.2 What makes a name “good”? 34 Expressive 35 ■ Simple 35 ■ Predictable 36 3.3 Language, grammar, and syntax 36 Language 37 ■ Grammar 37 ■ Syntax 40 3.4 Context 41 3.5 Data types and units 41 3.6 Case study: What happens when you choose bad names? 43 3.7 Exercises 45 4 Resource scope and hierarchy 47 4.1 What is resource layout? 48 Types of relationships 49 ■ Entity relationship diagrams 52 4.2 Choosing the right relationship 54 Do you need a relationship at all? 54 ■ References or in-line data 55 ■ Hierarchy 57 4.3 Anti-patterns 59 Resources for everything 59 ■ Deep hierarchies 61 In-line everything 63 4.4 Exercises 64 5 Data types and defaults 65 5.1 Introduction to data types 66 Missing vs. null 67 5.2 Booleans 68
Page
13
CONTENTS xi5.3 Numbers 69 Bounds 70 ■ Default values 71 ■ Serialization 71 5.4 Strings 73 Bounds 73 ■ Default values 74 ■ Serialization 75 5.5 Enumerations 76 5.6 Lists 77 Atomicity 77 ■ Bounds 78 ■ Default values 79 5.7 Maps 79 Bounds 82 ■ Default values 82 5.8 Exercises 82 PART 3 FUNDAMENTALS ................................................85 6 Resource identification 87 6.1 What is an identifier? 87 6.2 What makes a good identifier? 88 Easy to use 88 ■ Unique 88 ■ Permanent 89 Fast and easy to generate 89 ■ Unpredictable 90 Readable, shareable, and verifiable 90 ■ Informationally dense 91 6.3 What does a good identifier look like? 91 Data type 91 ■ Character set 92 ■ Identifier format 92 Checksums 93 ■ Resource type 93 ■ Hierarchy and uniqueness scope 94 6.4 Implementation 95 Size 95 ■ Generation 96 ■ Tomb-stoning 98 Checksum 98 ■ Database storage 100 6.5 What about UUIDs? 101 6.6 Exercises 102 7 Standard methods 104 7.1 Motivation 105 7.2 Overview 105 7.3 Implementation 106 Which methods should be supported? 106 ■ Idempotence and side effects 107 ■ Get 108 ■ List 109 ■ Create 112
Page
14
CONTENTSxiiUpdate 114 ■ Delete 115 ■ Replace 116 ■ Final API definition 118 7.4 Trade-offs 120 7.5 Exercises 120 8 Partial updates and retrievals 122 8.1 Motivation 123 Partial retrieval 123 ■ Partial update 123 8.2 Overview 125 8.3 Implementation 128 Transport 128 ■ Maps and nested interfaces 129 Repeated fields 132 ■ Default values 133 ■ Implicit field masks 135 ■ Updating dynamic data structures 136 Invalid fields 137 ■ Final API definition 138 8.4 Trade-offs 138 Universal support 139 ■ Alternative implementations 139 8.5 Exercises 140 9 Custom methods 141 9.1 Motivation 142 Why not just standard methods? 142 9.2 Overview 145 9.3 Implementation 146 Side effects 147 ■ Resources vs. collections 147 ■ Stateless custom methods 149 ■ Final API definition 151 9.4 Trade-offs 152 9.5 Exercises 152 10 Long-running operations 154 10.1 Motivation 155 10.2 Overview 156 10.3 Implementation 158 What does an LRO look like? 159 ■ Resource hierarchy 160 Resolution 160 ■ Error handling 164 ■ Monitoring progress 165 ■ Canceling operations 167 ■ Pausing and resuming operations 168 ■ Exploring operations 169 Persistence 170 ■ Final API definition 172
Page
15
CONTENTS xiii10.4 Trade-offs 173 10.5 Exercises 174 11 Rerunnable jobs 175 11.1 Motivation 176 11.2 Overview 176 11.3 Implementation 178 Job resources 178 ■ The custom run method 180 Job execution resources 181 ■ Final API definition 184 11.4 Trade-offs 186 11.5 Exercises 186 PART 4 RESOURCE RELATIONSHIPS ..............................187 12 Singleton sub-resources 189 12.1 Motivation 189 Why should we use a singleton sub-resource? 190 12.2 Overview 191 12.3 Implementation 192 Standard methods 192 ■ Resetting 195 ■ Hierarchy 195 Final API definition 196 12.4 Trade-offs 197 Atomicity 198 ■ Exactly one sub-resource 198 12.5 Exercises 198 13 Cross references 200 13.1 Motivation 200 13.2 Overview 201 13.3 Implementation 202 Reference field name 202 ■ Data integrity 203 ■ Value vs. reference 204 ■ Final API definition 206 13.4 Trade-offs 206 13.5 Exercises 206
Page
16
CONTENTSxiv14 Association resources 207 14.1 Motivation 207 14.2 Overview 208 Association alias methods 209 14.3 Implementation 210 Naming the association resource 210 ■ Standard method behavior 210 ■ Uniqueness 211 ■ Read-only fields 211 Association alias methods 212 ■ Referential integrity 213 Final API definition 214 14.4 Trade-offs 216 Complexity 216 ■ Separation of associations 216 14.5 Exercises 216 15 Add and remove custom methods 218 15.1 Motivation 219 15.2 Overview 219 15.3 Implementation 220 Listing associated resources 220 ■ Data integrity 221 Final API definition 222 15.4 Trade-offs 223 Nonreciprocal relationship 223 ■ Relationship metadata 223 15.5 Exercises 224 16 Polymorphism 225 16.1 Motivation 225 16.2 Overview 226 16.3 Implementation 227 Deciding when to use polymorphic resources 227 ■ Polymorphic structure 228 ■ Polymorphic behavior 232 ■ Why not polymorphic methods? 233 ■ Final API definition 234 16.4 Trade-offs 235 16.5 Exercises 235
Page
17
CONTENTS xvPART 5 COLLECTIVE OPERATIONS................................237 17 Copy and move 239 17.1 Motivation 240 17.2 Overview 240 17.3 Implementation 241 Identifiers 241 ■ Child resources 244 ■ Related resources 245 External data 247 ■ Inherited metadata 249 ■ Atomicity 250 Final API definition 252 17.4 Trade-offs 252 17.5 Exercises 253 18 Batch operations 254 18.1 Motivation 255 18.2 Overview 255 18.3 Implementation 256 Atomicity 256 ■ Operation on the collection 257 ■ Ordering of results 258 ■ Common fields 258 ■ Operating across parents 259 ■ Batch Get 261 ■ Batch Delete 263 ■ Batch Create 264 ■ Batch Update 265 ■ Final API definition 266 18.4 Trade-offs 269 18.5 Exercises 269 19 Criteria-based deletion 270 19.1 Motivation 271 19.2 Overview 271 19.3 Implementation 272 Filtering results 272 ■ Validation only by default 274 ■ Result count 275 ■ Result sample set 275 ■ Consistency 276 Final API definition 276 19.4 Trade-offs 277 19.5 Exercises 277 20 Anonymous writes 278 20.1 Motivation 278 20.2 Overview 279
Page
18
CONTENTSxvi20.3 Implementation 280 Consistency 281 ■ Final API definition 283 20.4 Trade-offs 283 20.5 Exercises 284 21 Pagination 285 21.1 Motivation 286 21.2 Overview 286 21.3 Implementation 287 Page size 288 ■ Page tokens 290 ■ Total count 293 Paging inside resources 294 ■ Final API definition 295 21.4 Trade-offs 296 Bi-directional paging 296 ■ Arbitrary windows 296 21.5 Anti-pattern: Offsets and limits 296 21.6 Exercises 298 22 Filtering 299 22.1 Motivation 300 22.2 Overview 300 22.3 Implementation 301 Structure 302 ■ Filter syntax and behavior 305 ■ Final API definition 310 22.4 Trade-offs 311 22.5 Exercises 311 23 Importing and exporting 313 23.1 Motivation 314 23.2 Overview 315 23.3 Implementation 316 Import and export methods 317 ■ Interacting with storage systems 318 ■ Converting between resources and bytes 319 Consistency 321 ■ Identifiers and collisions 322 ■ Handling related resources 323 ■ Failures and retries 324 ■ Filtering and field masks 327 ■ Final API definition 328 23.4 Trade-offs 330 23.5 Exercises 330
Page
19
CONTENTS xviiPART 6 SAFETY AND SECURITY .....................................333 24 Versioning and compatibility 335 24.1 Motivation 335 24.2 Overview 336 What is compatibility? 336 ■ Defining backward compatibility 338 24.3 Implementation 344 Perpetual stability 345 ■ Agile instability 346 Semantic versioning 349 24.4 Trade-offs 351 Granularity vs. simplicity 351 ■ Stability vs. new functionality 352 ■ Happiness vs. ubiquity 353 24.5 Exercises 355 25 Soft deletion 357 25.1 Motivation 358 25.2 Overview 358 25.3 Implementation 359 Deleted designation 359 ■ Modifying standard methods 362 Undeleting 364 ■ Expunging 365 ■ Expiration 366 Referential integrity 367 ■ Effects on other methods 367 Adding soft delete across versions 368 ■ Final API definition 368 25.4 Trade-offs 369 25.5 Exercises 369 26 Request deduplication 371 26.1 Motivation 371 26.2 Overview 373 26.3 Implementation 373 Request identifier 373 ■ Response caching 375 Consistency 376 ■ Request ID collisions 378 Cache expiration 380 ■ Final API definition 380 26.4 Trade-offs 382 26.5 Exercises 382
Page
20
CONTENTSxviii27 Request validation 383 27.1 Motivation 383 27.2 Overview 384 27.3 Implementation 385 External dependencies 387 ■ Special side effects 388 Final API definition 388 27.4 Trade-offs 389 27.5 Exercises 389 28 Resource revisions 390 28.1 Motivation 391 28.2 Overview 391 28.3 Implementation 392 Revision identifiers 392 ■ Creating revisions 394 Retrieving specific revisions 397 ■ Listing revisions 398 Restoring a previous revision 399 ■ Deleting revisions 400 Handling child resources 402 ■ Final API definition 402 28.4 Trade-offs 403 28.5 Exercises 404 29 Request retrial 405 29.1 Motivation 405 29.2 Overview 406 Client-side retry timing 407 ■ Server-specified retry timing 407 29.3 Implementation 408 Retry eligibility 408 ■ Exponential back-off 410 ■ Retry After 412 ■ Final API definition 414 29.4 Trade-offs 414 29.5 Exercises 415 30 Request authentication 416 30.1 Motivation 417 Origin 417 ■ Integrity 417 ■ Nonrepudiation 418 30.2 Overview 418
Comments 0
Loading comments...
Reply to Comment
Edit Comment