What Is a Web API?

536 Pages·2014·15.76 MB·English

Designing Evolvable Web APIs
with ASP.NET
Glenn Block, Pablo Cibraro, Pedro Felix,
Howard Dierking, and Darrel Miller
Designing Evolvable Web APIs with ASP.NET
by Glenn Block, Pablo Cibraro, Pedro Felix, Howard Dierking, and Darrel Miller
Copyright © 2014 Glenn Block, Pablo Cibraro, Pedro Felix, Howard Dierking, and Darrel Miller. 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://my.safaribooksonline.com). For more information, contact our corporate/
institutional sales department: 800-998-9938 or [email protected].
Editors: Rachel Roumeliotis and Amy Jollymore Indexer: Judy McConville
Production Editor: Nicole Shelby Cover Designer: Randy Comer
Copyeditor: Rachel Monaghan Interior Designer: David Futato
Proofreader: Rachel Head Illustrator: Kara Ebrahim
March 2014: First Edition
Revision History for the First Edition:
2014-03-11: First release
See http://oreilly.com/catalog/errata.csp?isbn=9781449337711 for release details.
Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly
Media, Inc. Designing Evolvable Web APIs with ASP.NET, the images of warty newts, and related trade dress
are trademarks of O’Reilly Media, Inc.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as
trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a trademark
claim, the designations have been printed in caps or initial caps.
While every precaution has been taken in the preparation of this book, the publisher and authors assume
no responsibility for errors or omissions, or for damages resulting from the use of the information contained
herein.
ISBN: 978-1-449-33771-1
[LSI]
Table of Contents
Foreword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
1. The Internet, the World Wide Web, and HTTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Web Architecture 2
Resource 3
URI 4
Cool URIs 5
Representation 5
Media Type 5
HTTP 8
Moving Beyond HTTP 1.1 8
HTTP Message Exchange 8
Intermediaries 10
Types of Intermediaries 11
HTTP Methods 12
Headers 15
HTTP Status Codes 16
Content Negotiation 17
Caching 17
Authentication 20
Authentication Schemes 21
Additional Authentication Schemes 22
Conclusion 22
2. Web APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
What Is a Web API? 23
What About SOAP Web Services? 23
Origins of Web APIs 24
iii
The Web API Revolution Begins 24
Paying Attention to the Web 24
Guidelines for Web APIs 25
Domain-Specific Media Types 25
Media Type Profiles 26
Multiple Representations 27
API Styles 29
The Richardson Maturity Model 29
RPC (RMM Level 0) 30
Resources (RMM Level 1) 31
HTTP VERBS (RMM Level 2) 33
Crossing the Chasm Toward Resource-Centric APIs 36
Hypermedia (RMM Level 3) 36
REST 41
REST Constraints 41
Conclusion 43
3. ASP.NET Web API 101. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Core Scenarios 45
First-Class HTTP Programming 46
Symmetric Client and Server Programming Experience 48
Flexible Support for Different Formats 48
No More “Coding with Angle Brackets” 48
Unit Testability 49
Multiple Hosting Options 50
Getting Started with ASP.NET Web API 50
Exploring a New Web API Project 54
WebApiConfig 54
ValuesController 56
“Hello Web API!” 58
Creating the Service 58
The Client 65
The Host 65
Conclusion 66
4. Processing Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
The Hosting Layer 70
Message Handler Pipeline 71
Route Dispatching 73
Controller Handling 75
The ApiController Base Class 75
iv | Table of Contents
Conclusion 82
5. The Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Why Evolvable? 84
Barriers to Evolution 85
What Is the Cost? 86
Why Not Just Version? 88
Walking the Walk 91
Application Objectives 91
Goals 92
Opportunity 92
Information Model 93
Subdomains 93
Related Resources 94
Attribute Groups 95
Collections of Attribute Groups 96
Information Model Versus Media Type 96
Collections of Issues 98
Resource Models 98
Root Resource 98
Search Resources 98
Collection Resources 99
Item Resources 99
Conclusion 102
6. Media Type Selection and Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Self-Description 103
Types of Contracts 104
Media Types 104
Primitive Formats 105
Popular Formats 107
New Formats 108
Hypermedia Types 110
Media Type Explosion 110
Generic Media Types and Profiles 110
Other Hypermedia Types 115
Link Relation Types 115
Semantics 116
Replacing Embedded Resources 118
Indirection Layer 118
Reference Data 119
Workflow 120
Table of Contents | v
Syntax 121
A Perfect Combination 124
Designing a New Media Type Contract 124
Selecting a Format 125
Enabling Hypermedia 126
Optional, Mandatory, Omitted, Applicable 126
Embedded Versus External Metadata 127
Extensibility 127
Registering the Media Type 129
Designing New Link Relations 130
Standard Link Relations 130
Extension Link Relations 131
Embedded Link Relations 131
Registering the Link Relation 132
Media Types in the Issue Tracking Domain 132
List Resources 132
Item Resources 134
Discovery Resource 135
Search Resource 136
Conclusion 136
7. Building the API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
The Design 137
Getting the Source 138
Building the Implementation Using BDD 138
Navigating the Solution 139
Packages and Libraries 139
Self-Host 140
Models and Services 141
Issue and Issue Store 141
IssueState 142
IssuesState 143
Link 144
IssueStateFactory 145
LinkFactory 146
IssueLinkFactory 147
Acceptance Criteria 149
Feature: Retrieving Issues 152
Retrieving an Issue 154
Retrieving Open and Closed Issues 157
Retrieving an Issue That Does Not Exist 159
Retrieving All Issues 160
vi | Table of Contents
Retrieving All Issues as Collection+Json 163
Searching Issues 165
Feature: Creating Issues 167
Feature: Updating Issues 170
Updating an Issue 170
Updating an Issue That Does Not Exist 172
Feature: Deleting Issues 173
Deleting an Issue 173
Deleting an Issue That Does Not Exist 175
Feature: Processing Issues 175
The Tests 175
The Implementation 176
Conclusion 177
8. Improving the API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Acceptance Criteria for the New Features 179
Implementing the Output Caching Support 181
Adding the Tests for Output Caching 182
Implementing Cache Revalidation 185
Implementing Conditional GETs for Cache Revalidation 186
Conflict Detection 189
Implementing Conflict Detection 189
Change Auditing 192
Implementing Change Auditing with Hawk Authentication 193
Tracing 197
Implementing Tracing 198
Conclusion 201
9. Building the Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Client Libraries 204
Wrapper Libraries 204
Links as Functions 208
Application Workflow 214
Need to Know 214
Clients with Missions 218
Client State 221
Conclusion 222
10. The HTTP Programming Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Messages 226
Headers 231
Message Content 237
Table of Contents | vii
Consuming Message Content 238
Creating Message Content 241
Conclusion 249
11. Hosting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Web Hosting 252
The ASP.NET Infrastructure 252
ASP.NET Routing 255
Web API Routing 257
Global Configuration 259
The Web API ASP.NET Handler 261
Self-Hosting 264
WCF Architecture 265
The HttpSelfHostServer Class 267
The HttpSelfHostConfiguration Class 268
URL Reservation and Access Control 270
Hosting Web API with OWIN and Katana 271
OWIN 271
The Katana Project 273
Web API Configuration 275
Web API Middleware 276
The OWIN Ecosystem 279
In-Memory Hosting 280
Azure Service Bus Host 281
Conclusion 286
12. Controllers and Routing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
HTTP Message Flow Overview 287
The Message Handler Pipeline 288
Dispatcher 292
HttpControllerDispatcher 293
Controller Selection 294
Controller Activation 298
The Controller Pipeline 299
ApiController 299
ApiController Processing Model 300
Conclusion 312
13. Formatters and Model Binding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
The Importance of Models in ASP.NET Web API 315
How Model Binding Works 317
Built-In Model Binders 320
viii | Table of Contents