Designing Evolvable Web APIs with ASP.NET

Designing Evolvable Web APIs with ASP.NET

by Glenn Block, Pablo Cibraro, Pedro Felix, Howard Dierking, Darrel Miller
Released March 2014
Publisher(s): O'Reilly Media, Inc.
ISBN: 9781449337896

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

Design and build Web APIs for a broad range of clients—including browsers and mobile devices—that can adapt to change over time. This practical, hands-on guide takes you through the theory and tools you need to build evolvable HTTP services with Microsoft’s ASP.NET Web API framework. In the process, you’ll learn how design and implement a real-world Web API.

Ideal for experienced .NET developers, this book’s sections on basic Web API theory and design also apply to developers who work with other development stacks such as Java, Ruby, PHP, and Node.

  • Dig into HTTP essentials, as well as API development concepts and styles
  • Learn ASP.NET Web API fundamentals, including the lifecycle of a request as it travels through the framework
  • Design the Issue Tracker API example, exploring topics such as hypermedia support with collection+json
  • Use behavioral-driven development with ASP.NET Web API to implement and enhance the application
  • Explore techniques for building clients that are resilient to change, and make it easy to consume hypermedia APIs
  • Get a comprehensive reference on how ASP.NET Web API works under the hood, including security and testability

Publisher resources

View/Submit Errata

Table of contents

  1. Foreword
  2. Preface
    1. Why Should You Read This Book?
    2. What Do You Need to Know to Follow Along?
    3. The Hitchhiker’s Guide to Navigating This Book
      1. Part I, Fundamentals
      2. Part II, Real-World API Development
      3. Part III, Web API Nuts and Bolts
    4. Conventions Used in This Book
    5. Using Code Examples
    6. Safari® Books Online
    7. How to Contact Us
    8. Acknowledgments
  3. 1. The Internet, the World Wide Web, and HTTP
    1. Web Architecture
      1. Resource
      2. URI
      3. Cool URIs
      4. Representation
      5. Media Type
        1. Media type registration
    2. HTTP
      1. Moving Beyond HTTP 1.1
      2. HTTP Message Exchange
      3. Intermediaries
      4. Types of Intermediaries
      5. HTTP Methods
        1. Conditional requests
        2. Method properties
      6. Headers
      7. HTTP Status Codes
      8. Content Negotiation
      9. Caching
        1. Expiration
        2. Validation
        3. Invalidation
        4. ETags
        5. Caching and negotiated responses
        6. Cache behaviors
      10. Authentication
      11. Authentication Schemes
      12. Additional Authentication Schemes
    3. Conclusion
  4. 2. Web APIs
    1. What Is a Web API?
    2. What About SOAP Web Services?
    3. Origins of Web APIs
    4. The Web API Revolution Begins
    5. Paying Attention to the Web
    6. Guidelines for Web APIs
    7. Domain-Specific Media Types
    8. Media Type Profiles
    9. Multiple Representations
    10. API Styles
      1. The Richardson Maturity Model
      2. RPC (RMM Level 0)
      3. Resources (RMM Level 1)
      4. HTTP VERBS (RMM Level 2)
      5. Crossing the Chasm Toward Resource-Centric APIs
      6. Hypermedia (RMM Level 3)
      7. REST
      8. REST Constraints
    11. Conclusion
  5. 3. ASP.NET Web API 101
    1. Core Scenarios
      1. First-Class HTTP Programming
      2. Symmetric Client and Server Programming Experience
      3. Flexible Support for Different Formats
      4. No More “Coding with Angle Brackets”
      5. Unit Testability
      6. Multiple Hosting Options
    2. Getting Started with ASP.NET Web API
    3. Exploring a New Web API Project
      1. WebApiConfig
      2. ValuesController
    4. “Hello Web API!”
      1. Creating the Service
        1. A read-only greeting service
        2. Content negotiation
        3. Add a greeting
        4. Handling errors
        5. Testing the API
      2. The Client
      3. The Host
    5. Conclusion
  6. 4. Processing Architecture
    1. The Hosting Layer
    2. Message Handler Pipeline
      1. Route Dispatching
    3. Controller Handling
      1. The ApiController Base Class
        1. Parameter binding
        2. Conversion into an HttpResponseMessage
        3. Filters
    4. Conclusion
  7. 5. The Application
    1. Why Evolvable?
      1. Barriers to Evolution
      2. What Is the Cost?
      3. Why Not Just Version?
        1. Payload-based versioning
        2. Versioning the media type
        3. Versioning in the URL
      4. Walking the Walk
    2. Application Objectives
      1. Goals
      2. Opportunity
    3. Information Model
      1. Subdomains
        1. Descriptive
        2. Categorization
        3. Current state
        4. Historical
      2. Related Resources
      3. Attribute Groups
      4. Collections of Attribute Groups
      5. Information Model Versus Media Type
      6. Collections of Issues
    4. Resource Models
      1. Root Resource
      2. Search Resources
      3. Collection Resources
      4. Item Resources
    5. Conclusion
  8. 6. Media Type Selection and Design
    1. Self-Description
    2. Types of Contracts
    3. Media Types
      1. Primitive Formats
      2. Popular Formats
      3. New Formats
      4. Hypermedia Types
      5. Media Type Explosion
      6. Generic Media Types and Profiles
      7. Other Hypermedia Types
        1. Collection+Json
        2. Siren
    4. Link Relation Types
      1. Semantics
      2. Replacing Embedded Resources
      3. Indirection Layer
      4. Reference Data
      5. Workflow
      6. Syntax
      7. A Perfect Combination
    5. Designing a New Media Type Contract
      1. Selecting a Format
      2. Enabling Hypermedia
      3. Optional, Mandatory, Omitted, Applicable
      4. Embedded Versus External Metadata
      5. Extensibility
      6. Registering the Media Type
    6. Designing New Link Relations
      1. Standard Link Relations
      2. Extension Link Relations
      3. Embedded Link Relations
      4. Registering the Link Relation
    7. Media Types in the Issue Tracking Domain
      1. List Resources
      2. Item Resources
      3. Discovery Resource
      4. Search Resource
    8. Conclusion
  9. 7. Building the API
    1. The Design
    2. Getting the Source
    3. Building the Implementation Using BDD
    4. Navigating the Solution
    5. Packages and Libraries
    6. Self-Host
    7. Models and Services
      1. Issue and Issue Store
      2. IssueState
      3. IssuesState
      4. Link
      5. IssueStateFactory
      6. LinkFactory
      7. IssueLinkFactory
    8. Acceptance Criteria
    9. Feature: Retrieving Issues
      1. Retrieving an Issue
        1. Understanding the tests
      2. Retrieving Open and Closed Issues
      3. Retrieving an Issue That Does Not Exist
      4. Retrieving All Issues
      5. Retrieving All Issues as Collection+Json
      6. Searching Issues
    10. Feature: Creating Issues
    11. Feature: Updating Issues
      1. Updating an Issue
      2. Updating an Issue That Does Not Exist
    12. Feature: Deleting Issues
      1. Deleting an Issue
      2. Deleting an Issue That Does Not Exist
    13. Feature: Processing Issues
      1. The Tests
      2. The Implementation
    14. Conclusion
  10. 8. Improving the API
    1. Acceptance Criteria for the New Features
    2. Implementing the Output Caching Support
    3. Adding the Tests for Output Caching
    4. Implementing Cache Revalidation
    5. Implementing Conditional GETs for Cache Revalidation
    6. Conflict Detection
    7. Implementing Conflict Detection
    8. Change Auditing
    9. Implementing Change Auditing with Hawk Authentication
    10. Tracing
    11. Implementing Tracing
    12. Conclusion
  11. 9. Building the Client
    1. Client Libraries
      1. Wrapper Libraries
        1. Reliability
        2. Response types
        3. Lifetime
        4. Everyone has his or her own style
        5. Hypermedia hostile
      2. Links as Functions
        1. Service antipattern
        2. Deserializing links
        3. Separating request and response
        4. Links as bookmarks
    2. Application Workflow
      1. Need to Know
        1. Handle all the versions
        2. Change is inevitable
      2. Clients with Missions
      3. Client State
    3. Conclusion
  12. 10. The HTTP Programming Model
    1. Messages
    2. Headers
    3. Message Content
      1. Consuming Message Content
      2. Creating Message Content
        1. Content length and streaming
        2. Custom content classes
    4. Conclusion
  13. 11. Hosting
    1. Web Hosting
      1. The ASP.NET Infrastructure
        1. Applications
        2. Modules
        3. Handlers
      2. ASP.NET Routing
      3. Web API Routing
      4. Global Configuration
      5. The Web API ASP.NET Handler
    2. Self-Hosting
      1. WCF Architecture
      2. The HttpSelfHostServer Class
      3. The HttpSelfHostConfiguration Class
      4. URL Reservation and Access Control
    3. Hosting Web API with OWIN and Katana
      1. OWIN
      2. The Katana Project
      3. Web API Configuration
      4. Web API Middleware
      5. The OWIN Ecosystem
    4. In-Memory Hosting
    5. Azure Service Bus Host
    6. Conclusion
  14. 12. Controllers and Routing
    1. HTTP Message Flow Overview
    2. The Message Handler Pipeline
      1. Dispatcher
      2. HttpControllerDispatcher
      3. Controller Selection
        1. Supporting attribute-based routes
        2. Plugging in a custom controller selector
      4. Controller Activation
    3. The Controller Pipeline
      1. ApiController
      2. ApiController Processing Model
        1. Action selection
        2. Filters
        3. Authentication filters
        4. Authorization filters
        5. Action filters
        6. Exception filters
        7. Model binding and validation
        8. Action invocation
    4. Conclusion
  15. 13. Formatters and Model Binding
    1. The Importance of Models in ASP.NET Web API
    2. How Model Binding Works
    3. Built-In Model Binders
      1. The ModelBindingParameterBinder Implementation
      2. Value Providers
      3. Model Binders
      4. Model Binding Against URIs Only
      5. The FormatterParameterBinder Implementation
      6. Default HttpParameterBinding Selection
    4. Model Validation
      1. Applying Data Annotation Attributes to a Model
      2. Querying the Validation Results
    5. Conclusion
  16. 14. HttpClient
    1. HttpClient Class
      1. Lifecycle
      2. Wrapper
      3. Multiple Instances
      4. Thread Safety
      5. Helper Methods
      6. Peeling Off the Layers
      7. Completed Requests Don’t Throw
      8. Content Is Everything
      9. Cancelling the Request
      10. SendAsync
    2. Client Message Handlers
      1. Proxying Handlers
      2. Fake Response Handlers
      3. Creating Resuable Response Handlers
    3. Conclusion
  17. 15. Security
    1. Transport Security
    2. Using TLS in ASP.NET Web API
      1. Using TLS with IIS Hosting
      2. Using TLS with Self-Hosting
    3. Authentication
      1. The Claims Model
      2. Retrieving and Assigning the Current Principal
      3. Transport-Based Authentication
      4. Server Authentication
      5. Client Authentication
      6. The HTTP Authentication Framework
      7. Implementing HTTP-Based Authentication
      8. Katana Authentication Middleware
      9. Active and Passive Authentication Middleware
      10. Web API Authentication Filters
      11. Token-Based Authentication
      12. The Hawk Authentication Scheme
    4. Authorization
      1. Authorization Enforcement
      2. Cross-Origin Resource Sharing
      3. CORS Support on ASP.NET Web API
    5. Conclusion
  18. 16. The OAuth 2.0 Authorization Framework
    1. Client Applications
    2. Accessing Protected Resources
    3. Obtaining Access Tokens
    4. Authorization Code Grant
    5. Scope
    6. Front Channel Versus Back Channel
    7. Refresh Tokens
    8. Resource Server and Authorization Server
    9. Processing Access Tokens in ASP.NET Web API
    10. OAuth 2.0 and Authentication
    11. Scope-Based Authorization
    12. Conclusion
  19. 17. Testability
    1. Unit Tests
      1. Unit Testing Frameworks
      2. Getting Started with Unit Testing in Visual Studio
      3. xUnit.NET
        1. Unit test organization
        2. The Assert class
      4. The Role of Unit Testing in Test-Driven Development
        1. The red and green cycle
        2. Code refactoring
        3. Dependency injection and mocking
    2. Unit Testing an ASP.NET Web API Implementation
      1. Unit Testing an ApiController
        1. Testing the Get method
        2. Testing the Post method
        3. IHttpActionResult in Web API 2
      2. Unit Testing a MediaTypeFormatter
      3. Unit Testing an HttpMessageHandler
      4. Unit Testing an ActionFilterAttribute
    3. Unit Testing Routes
    4. Integration Tests in ASP.NET Web API
    5. Conclusion
  20. A. Media Types
  21. B. HTTP Headers
  22. C. Content Negotiation
    1. Proactive Negotiation
    2. Reactive Negotiation
  23. D. Caching in Action
  24. E. Authentication Workflows
  25. F. Media Type Specification for application/issue+json
    1. Notational Conventions
    2. Issue Documents
    3. Security Considerations
    4. Interoperability Considerations
    5. IANA Considerations
  26. G. Public-Key Cryptography and Certificates
    1. Revocation
    2. Creating Test Keys and Certificates
  27. Index
  28. Colophon
  29. Copyright

Product information

  • Title: Designing Evolvable Web APIs with ASP.NET
  • Author(s): Glenn Block, Pablo Cibraro, Pedro Felix, Howard Dierking, Darrel Miller
  • Release date: March 2014
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9781449337896