designing evolvable web apis with asp.net 2

www.it-ebooks.info www.it-ebooks.info Glenn Block, Pablo Cibraro, Pedro Felix, Howard Dierking, and Darrel Miller Designing Evolvable Web APIs with ASP.NET www.it-ebooks.info 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 corporate@oreilly.com. Editors: Rachel Roumeliotis and Amy Jollymore Production Editor: Nicole Shelby Copyeditor: Rachel Monaghan Proofreader: Rachel Head Indexer: Judy McConville Cover Designer: Randy Comer Interior Designer: David Futato 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] www.it-ebooks.info 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 www.it-ebooks.info 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 www.it-ebooks.info 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 www.it-ebooks.info 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 www.it-ebooks.info 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 www.it-ebooks.info 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 www.it-ebooks.info [...]... Tokens in ASP.NET Web API OAuth 2. 0 and Authentication Scope-Based Authorization Conclusion 4 12 414 415 417 420 421 423 424 426 428 431 4 32 17 Testability 435 Unit Tests Unit Testing Frameworks Getting Started with Unit Testing in Visual Studio xUnit.NET The Role of Unit Testing in Test-Driven Development Unit Testing an ASP.NET Web API Implementation... comprehensive overview of the stateof-the-art methods for designing web APIs that can adapt to the changing demands of providers and consumers By introducing concepts such as hypermedia-driven web APIs with TDD, it provides an excellent starting point for anybody building web APIs As part of the team that built ASP.NET Web API, I have had the pleasure to work with the authors of this book The group stands out,... around web API development It covers the foundations of the Web/ HTTP and API development, and introduces you to ASP.NET Web API If you are new to web API development /ASP.NET Web API, this is a great place to start If you’ve been using ASP.NET Web API (or another Web API stack) but would like to learn more about how to take advantage of HTTP, this is also a good starting point • Part II centers on web. .. How to actually build such web APIs is where this book comes in In short, it is for anyone who is building web APIs targeting HTML5 appli‐ cations as well as mobile applications It provides not only a great introduction to web APIs but also a practical set of guidelines for how to build them using ASP.NET Web API In addition, it goes into great detail describing how ASP.NET Web API works and also serves... for you to walk away with the tools to be able to build a real, evolvable system To get you there, we’ll start by covering some essentials of the Web and web API development Then we’ll take you through the creation of a new API using ASP.NET Web API, from its design through implementation The implementation will cover important topics like how to imple‐ ment hypermedia with ASP.NET Web API and how to... You should ideally also have some experience building web APIs Which framework you have used to develop those APIs is not important; what is important is having familiarity with the concepts It is not necessary to have any prior experience with ASP.NET Web API or ASP.NET, though familiarity with ASP.NET MVC will definitely help If you are not a NET developer, then there is something here for you One specific... comfortable with web API development and in a hurry to start building an app, jump right to the second section • Part III is a fairly comprehensive reference on exactly how the different parts of ASP.NET Web API work under the hood It also covers more advanced topics like security and testability If you are already building an app with ASP.NET Web API and trying to figure out how to best utilize Web API... The Internet, the World Wide Web, and HTTP This chapter starts with a bit of history about the World Wide Web and HTTP It then gives you a 5,000-foot view of HTTP You can think of it as a “Dummies’ Guide” to HTTP, giving you the essentials you need to know, without your having to read the entire spec Chapter 2, Web APIs This chapter begins by giving a historical context on web API development in gen‐... remainder of the chapter discusses essentials of API development, starting with core concepts and then diving into different styles and approaches for de‐ signing APIs Chapter 3, ASP.NET Web API 101 This chapter discusses the fundamental drivers behind ASP.NET Web API as a framework It will then introduce you to the basics of ASP.NET Web API as well as the NET HTTP programming model and client Preface www.it-ebooks.info... appreciate, but do not require, attribution An attribution usually includes the title, author, publisher, and ISBN For example: Designing Evolvable Web APIs with ASP.NET by Glenn Block, Pablo Cibraro, Pedro Felix, Howard Dierking, and Darrel Miller (O’Reilly) Copyright 20 12 Glenn Block, Pablo Cibraro, Pedro Felix, Howard Dierking, and Darrel Miller, 978-1-449-33771-1.” If you feel your use of code . . . 25 1 Web Hosting 25 2 The ASP. NET Infrastructure 25 2 ASP. NET Routing 25 5 Web API Routing 25 7 Global Configuration 25 9 The Web API ASP. NET Handler 26 1 Self-Hosting 26 4 WCF Architecture 26 5 The. . 23 What Is a Web API? 23 What About SOAP Web Services? 23 Origins of Web APIs 24 iii www.it-ebooks.info The Web API Revolution Begins 24 Paying Attention to the Web 24 Guidelines for Web APIs. Pedro Felix, Howard Dierking, and Darrel Miller Designing Evolvable Web APIs with ASP. NET www.it-ebooks.info Designing Evolvable Web APIs with ASP. NET by Glenn Block, Pablo Cibraro, Pedro Felix,