Cover image for Designing Evolvable Web APIs with ASP.NET

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.

Table of Contents

  1. Preface
    1. Conventions Used in This Book
    2. Using Code Examples
    3. Safari® Books Online
    4. How to Contact Us
  2. 1. The Internet, the World Wide Web and HTTP
    1. Web Architecture
      1. Resource
        1. Is a Resource an Entity
      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
        1. Message Headers
        2. Request Headers
        3. Response Headers
        4. Representation 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 Schemes
      11. Delegated Authorization
        1. OAuth
        2. OZ
        3. Where to go next
  3. 2. Web APIs
    1. What is a Web API?
      1. What about SOAP web services?
    2. Origins of Web APIs
    3. 2005, The Web API revolution begins
    4. Paying attention to the Web
    5. Guidelines for Web APIs
    6. Domain specific media types
      1. Media Type profiles
    7. Multiple representations
    8. 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
  4. 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. Stop “coding with angle brackets”
      5. Unit-testable
      6. Multiple hosting options
    2. Getting Started with ASP.NET Web API
      1. Exploring a New Web API Project
        1. WebApiConfig
        2. ValuesController
    3. “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
    4. Conclusion
  5. 4. Processing Architecture
    1. The Hosting layer
    2. Message handler pipeline
      1. Route dispatching
    3. Controller Handling
      1. The
        1. Parameter binding
        2. Conversion into an
        3. Filters
    4. Conclusion
  6. 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. Sub domains
        1. Descriptive
        2. Categorization
        3. Current State
        4. Historical
      2. Related resources
      3. Attribute groups
      4. Collections of attribute groups
      5. Collections of issues
    4. Resource Models
      1. Root resource
      2. Search resources
      3. Collection resources
      4. Detail resources
  7. 6. Media Type Selection and Design
    1. Introduction
      1. Self Description
      2. Types of contracts
    2. Media Types
      1. Primitive formats
      2. Popular formats
      3. New formats
      4. Media type explosion
      5. Generic hypermedia
    3. Link Relation Types
      1. Semantics
      2. Replacing embedded resources
      3. Indirection layer
      4. Reference data
      5. Workflow
      6. Syntax
      7. A perfect combination
    4. Designing a new Media Type contract
      1. Selecting a format
      2. Enabling Hypermedia
      3. Optional, Mandatory, Omitted, Applicable
      4. Embedded vs External Metadata
      5. Extensibility
      6. Registering the media type
    5. Designing new Link Relations
      1. Standard Link Relations
      2. Extension Link Relations
      3. Embedded Link Relations
      4. Registering the link relation
    6. Media Types in the Issue Tracking Domain
      1. Item Resources
      2. Discovery Resource
      3. Search Resource
  8. 7. 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
      3. The
      4. URL reservation and access control
    3. Azure Service Bus Host
    4. In-memory hosting
    5. 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
  9. 8. Controllers and Routing
    1. HTTP Message Flow Overview
    2. The Message Handler Pipeline
      1. Dispatcher
      2. HttpControllerDispatcher
      3. Controller Selection
        1. 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. Model Binding and Validation
        4. Action Invocation
    4. Summary
  10. 9. The HTTP Programming Model
    1. Messages
    2. Headers
    3. Message content
      1. Consuming message content
      2. Creating message content
        1. Content lenght and streaming
        2. Custom content classes
    4. Summary
  11. 10. 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 Annotations attributes to a model
      2. Querying the validation results
    5. Summary
  12. 11.
    1. Background
    2. HttpClient Class
      1. Lifecycle
      2. Wrapper
      3. Multiple Instances
      4. Thread Safe
      5. Helper methods
      6. Peeling off the layers
      7. Completed requests don’t throw
      8. Content is everything
      9. Cancelling the request
      10. SendAsync
    3. HttpRequestMessage
      1. Headers
    4. HttpResponseMessage
      1. Headers
    5. HttpContent
      1. Headers
      2. Custom HttpContent Classes
    6. Client MessageHandlers
    7. Building Reactive clients
      1. Routing responses through a common path
      2. Breaking the request response pair.
      3. Creating resuable response handlers
  13. 12. Testability
    1. Unit Tests
      1. Unit Testing Frameworks
      2. Getting started with Unit Testing in Visual Studio
      3. xUnit.NET
        1. Unit tests 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 a ASP.NET Web API
      1. Unit Testing a ApiController
        1. Testing the Get method
        2. Testing Post method
      2. Unit Testing a MediaTypeFormatter
      3. Unit Testing a HttpMessageHandler
    3. Unit Testing Routes
    4. Integration Tests in ASP.NET Web API
    5. Summary
  14. 13. Appendix
    1. Appendix A - Media Types
    2. Appendix B - HTTP Headers
    3. Appendix C - Content Negotiation
      1. Proactive Negotiation
      2. Reactive Negotiation
    4. Appendix D - Caching in action
    5. Appendix E - Authentication workflows
    6. Appendix E - Media Type Specification for application/issue+json
      1. Introduction
      2. Notational Conventions
      3. Issue Documents
      4. Security Considerations
      5. IANA Considerations
  15. About the Authors
  16. Copyright