Irresistible APIs Designing web APIs that developers will love

234 Pages·2016·16.11 MB·English

by  Kirsten Hunter

Irresistible APIs
DESIGNING WEB APIS
THAT DEVELOPERS WILL LOVE
KIRSTEN L. HUNTER
MANNING
SHELTER ISLAND
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: [email protected]
©2017 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. Development editor: Lesley Trites
20 Baldwin Road Technical development editor: Nick Watts
PO Box 761 Copyeditor: Elizabeth Welch
Shelter Island, NY 11964 Proofreader: Corbin Collins
Technical proofreader: David Fombella Pombal
Typesetter: Dottie Marsico
Illustrator: Viseslav Radovic
Cover designer: Leslie Haimes
ISBN 9781617292552
Printed in the United States of America
1 2 3 4 5 6 7 8 9 10 – EBM – 21 20 19 18 17 16
brief contents
PART 1 UNDERSTANDING WEB APIS.......................................... 1
1 ■ What makes an API irresistible? 3
2 ■ Working with web APIs 27
3 ■ API First 49
4 ■ Web services explained 64
PART 2 DESIGNING WEB APIS..................................................87
5 ■ Guiding principles for API design 89
6 ■ Defining the value for your API 114
7 ■ Creating your schema model 135
8 ■ Design-driven development 160
9 ■ Empowering your developers 183
iii

contents
foreword xi
preface xiii
acknowledgments xv
about this book xvi
about the cover illustration xviii
PART 1 UNDERSTANDING WEB APIS...............................1
1 What makes an API irresistible? 3
1.1 Integrating social APIs into web content 4
1.2 What is a web API? 7
Do you need an API? 10 ■ Choosing REST APIs 10
JSON 10
1.3 Developer experience 11
Versioning 12 ■ Marketing to developers 12
1.4 Common pitfalls of organic APIs 13
Lack of vision 13 ■ Prioritizing the developer experience 14
Bad API design 15
1.5 API creation process 16
Determine your business value 17 ■ Choose your
metrics 17 ■ Define your use cases 18 ■ Design your API 19
v
vi CONTENTS
Industry standards 22 ■ Design-driven
development 24 ■ Support your developers 25
1.6 Summary 26
2 Working with web APIs 27
2.1 HTTP basics 28
HTTP request 28 ■ HTTP response 29 ■ HTTP
interactions 30
2.2 The Toppings API 30
2.3 Designing the API 32
2.4 Using a web API 34
Browser 34 ■ Command line (curl) 36 ■ HTTP
sniffers 38
2.5 Interaction between the API and client 40
2.6 Install your own API and front end 45
Installing the system via Docker 45 ■ Installing the
system via Git 46 ■ Exploring the code 47
2.7 Summary 48
3 API First 49
3.1 Why choose API First? 50
APIs as side products 50 ■ API First model 52
3.2 Code consistency 53
3.3 Functional equality 54
3.4 Increased productivity 55
3.5 Internal/external access 56
3.6 Case studies 58
API as the main product 58 ■ Mobile First 59
Refactoring for API First 59 ■ API First strategic
direction 61
3.7 Summary 62
4 Web services explained 64
4.1 HTTP fundamentals 65
Addressability 65 ■ Status codes 66 ■ Body 68
HTTP verbs 68 ■ Headers 73 ■ Parameters 75
HTTP overview summary 77
CONTENTS vii
4.2 REST web services explained 77
4.3 Exploring your API by inspecting HTTP traffic 77
Setting up Chrome for HTTP inspection 78
4.4 Web services best practices 82
Using the right status codes 82 ■ Methods and idempotency 83
Nouns vs. verbs 83
4.5 Troubleshooting web API interactions 83
Tools for API inspection 84 ■ Error handling 84
Defensive coding 84
4.6 Summary 85
PART 2 DESIGNING WEB APIS ..................................... 87
5 Guiding principles for API design 89
5.1 Don’t surprise your users 90
Flickr API example 91 ■ Don’t make me think 94
5.2 Focus on use cases 95
Use case: mobile 96 ■ Use case: application integration 97
5.3 Copy successful APIs 101
5.4 REST is not always best 104
Expand and include related resources 104 ■ Create a query
language 105 ■ Create a comprehensive data transfer
scheme 106 ■ Create a separate batching system 108
RESTful decisions 109
5.5 Focus on the developer experience 109
Communication and consistency are critical 109
Documentation should tell a story 111
5.6 Summary 113
6 Defining the value for your API 114
6.1 Business goals 115
Monetization 115 ■ Usage 118 ■ Partner retention 120
Market dominance 122
6.2 Metrics 124
Poor metrics 124 ■ Monetization 124 ■ Usage 126
Partner retention 126 ■ Market dominance 126
viii CONTENTS
6.3 Use cases 127
Mobile 127 ■ Monetization 128 ■ Usage 130
Customer/partner retention 133
6.4 Summary 134
7 Creating your schema model 135
7.1 What is a schema model? 136
7.2 What does the API need to do? 136
Top-level resources 137 ■ API resource methods 137
7.3 RAML 138
Getting started 139 ■ Step 1: adding resources 141
Step 2: adding the methods 141 ■ Step 3: query parameters 142
Step 4: adding mock data 143 ■ Step 5: adding mock data—
GET 143 ■ Step 6: adding mock data—POST 144 ■ Step 7:
GET response format 146 ■ Step 8: PUT response format 147
Step 9: DELETE 147 ■ Step 10: searching 148 ■ Support tools
for RAML 149
7.4 OpenAPI (previously Swagger) 149
Information about your API 150 ■ Step 1: API top-level resource
methods: GET 151 ■ Step 2: API top-level resource methods—
POST 153 ■ Step 3: API subresource methods—GET, PUT,
DELETE 155 ■ OpenAPI tools and resources 158
7.5 Summary 158
8 Design-driven development 160
8.1 Development strategies for your API 160
Waterfall development 161 ■ Agile/test-first development 162
Behavior-driven development 164 ■ Design-driven
development 164 ■ Code-first development 165
Why does project management matter? 165
8.2 Project management for APIs 166
Functional specification 166 ■ Schema model 168
8.3 Road-testing your API 169
Creating a mock server API 169 ■ Acceptance tests and use
cases 176
8.4 Planning development 178
8.5 Development sprints 179
8.6 Summary 182
CONTENTS ix
9 Empowering your developers 183
9.1 Pillars of developer experience 184
9.2 Communicating with your developers 185
Failures of communication 185 ■ Strong communication 186
Advantages to strong and consistent communication 187
9.3 Documenting your API 189
Reference documentation 190 ■ Workflows 192
Tutorials 193
9.4 Building blocks 196
Sample code 197 ■ Reference applications 199
Tools and techniques 200
9.5 Developer support 203
Interactive 204 ■ Noninteractive 206
9.6 Summary 206
index 207