Building ASP.NET Web APIs

HTTP Protocol

You can't start developing for the web without knowing the fundamentals. This module talks about the HTTP protocol used to request resources from the server. We'll explore the history and details of what is used for a browser and for a server to make sure the communication is legitimate.

• Introduction to the World Wide Web
• URLs, Methods and Media Types
• Headers and Status Codes
• Reading Raw Requests and Responses
• Idempotency and Safeness
• Testing APIs with HTTP Files
• LAB: Calling a Public API with an HTTP File

Your First Web API

In this module you will get acquainted with the most important building blocks for any ASP.NET Core Web API application. You will create a project, see how Minimal APIs and controllers compare, and build one of each. This is the foundation of all following chapters.

• Creating a Web API Project
• Minimal APIs versus Controllers
• Building a Controller-Based API
• Building a Minimal API
• Testing with the Endpoints Explorer and HTTP Files
• LAB: Your First Web API

REST and API Design

A good API is designed before it is written. REST is more than mapping HTTP methods onto a database: it is a set of constraints that make your API predictable for the people consuming it. In this module you will learn how to organise your resources, how to shape requests and responses, and how to design an error contract your clients can rely on.

• REST and the HTTP Protocol
• Organizing Resources and Relationships
• Request and Response Types
• Limiting Data and Dealing with Batches
• Designing the Error Contract
• Internal versus Public APIs
• REST Alternatives: gRPC, SignalR and GraphQL
• LAB: Designing a RESTful Bookstore API

Inside the Request Pipeline

ASP.NET Core is Microsoft's framework for building all sorts of modern web applications. In this module we'll take a look at how it processes requests, and how the services your application needs end up in the container.

• What is ASP.NET Core?
• The Request Processing Pipeline
• Registering Dependencies
• LAB: The ASP.NET Core Pipeline

Dependency Injection

Dependency Injection is the art of decoupling an object from its dependencies. On top of improving maintainability and separation of concerns, it also makes testing a lot easier. This module shows you what is wrong with tightly coupled code, and how an Inversion of Control container solves it.

• Tightly Coupled Dependencies
• Decoupling Dependencies
• Using an Inversion of Control Container

Services and Dependency Injection

ASP.NET Core comes with a dependency injection container built right in. In this module you will register and consume your own services, pick the right life-cycle for each of them, and learn to recognise the mistakes that are easy to make along the way.

• Services
• Inversion of Control Containers in .NET
• Microsoft Dependency Injection
• Constructor and Property Injection
• Understanding DI life-cycle: Singleton, Scoped and Transient
• Minimal APIs and Dependency Injection
• Dependency Gotchas
• LAB: Dependency Injection in Web API

Routing and Endpoints

On the web the URL decides what the server will do. In ASP.NET Core you will find the Endpoint Routing Middleware. A solid understanding of this middleware is required to build applications with ASP.NET Core.

• Why Routing
• Routing Templates and Parameters
• Route Parameter Constraints
• Custom Route Constraints
• Route Matching and Priority
• Controllers: Attribute Routing
• Minimal API: Endpoint Groups
• Naming Endpoints and Generating URLs
• LAB: Routing and Endpoints

Requests: Binding and Validation

People could be sending any data to your API. So you should always validate your input. In this module we'll first look at how ASP.NET Core turns a raw request into your model, and then explore best practices for input validation, including built-in ASP.NET Core validation and the popular FluentValidation library.

• Model Binding
• Changing Model Binding Behavior
• Custom Model Binders
• Binding in Minimal APIs
• Validation Options
• Validation Attributes
• Validatable Objects
• FluentValidation
• LAB: Requests, Binding and Validation

Responses: Results and Serialization

What comes out of your API matters just as much as what goes in. In this module you will learn how to return data from both controllers and Minimal APIs, how to pick a status code that actually says something, and how content negotiation decides the format of your response.

• Returning Data from an API
• Response Types in Minimal APIs
• Response Types with Controllers
• Choosing the Right Status Code
• Media Types and Content Negotiation
• LAB: Responses, Results and Serialization

Cross-Cutting Concerns

Logging, error handling and authorization checks are needed all over your application, but you don't want to repeat them in every single endpoint. ASP.NET Core gives you middleware, endpoint filters and controller filters to do exactly that. In this module you will learn which one to reach for.

• Cross-Cutting Concerns and Middleware
• Minimal API Endpoint Filters
• Controller Filters
• Error Handling
• Choosing the Right Tool
• LAB: Handling Cross-Cutting Concerns with Filters and Middleware

ASP.NET Core Configuration

ASP.NET Core allows you to pick and choose where to store your configuration. No more deploying configuration with production settings in source control! We will look at the idea behind this and of course how to choose your ideal configuration.

• No more web.config?
• Formats: JSON, INI or XML
• Environment Variables
• Storing sensitive configuration in User Secrets
• Binding to Configuration
• Using the Options Pattern
• Multiple Configuration Containers
• LAB: Using ASP.NET Core Configuration and Feature Toggles

Data Access with Entity Framework Core

Most Web APIs expose data that lives in a database. Entity Framework Core is the default way to get to that data in .NET. In this module you will learn how to use a DbContext in a Web API, how to keep your queries efficient, and how to shape the result you hand back to the client.

• What is Entity Framework Core?
• The DbContext in a Web API
• Querying with LINQ
• Shaping the Result
• Efficient API Queries
• Modifying Data
• LAB: Data Access with Entity Framework Core

Documenting with OpenAPI

When you want to consume a REST service, you are dependent on the documentation of the service. And developers don't like to write documentation. No problem: using OpenAPI you can automatically generate the necessary metadata for describing your service functionalities.

• Why OpenAPI
• Generating the Document
• Describing Endpoints with Metadata
• Enriching your Metadata with Attributes and XML Comments
• Transformers
• Using the Document: Scalar, Client Generation and Build-time Output
• LAB: Documenting with OpenAPI

Versioning and Evolving Your API

Your API will change, but your clients will not change along with it. In this module you will learn how to add new features without breaking the consumers you already have, and how to warn them when a version is on its way out.

• Why API Versioning?
• Microsoft Versioning Library
• Deprecation and Sunset Signalling
• Versioning the OpenAPI Document
• LAB: Versioning and Evolving Your API

Securing a Web API

Security is a world on its own. In this module we'll explore common techniques to secure your Web API.

• Authentication and Authorization in Web API
• Using Claims in .NET
• Using Authorization Attributes and Policies
• Securing Minimal API Endpoints
• Authentication and Authorization with OpenID Connect
• LAB: Protecting a Web API with OAuth

Protecting the API

Securing your API is not only about who is calling. You also decide which frontends are allowed to talk to you, and you make sure a single client cannot take your service down.

• Giving Frontends Access to your API with CORS
• Setting Up Rate Limiting
• LAB: Protecting the API with CORS and Rate Limiting

API Performance

This module reveals some great ways to keep your API quick and responsive. Ranging from tweaks that decrease load on the server, to dealing with large resources in an efficient way, improving startup time and resource efficiency.

• Making your Backend Asynchronous
• Dealing with Cancellation
• Taking Advantage of Server-side and Client-side caching
• Handling Large Resources
• Improving Resource Efficiency and Startup Time with Ahead of Time Compilation
• LAB: Performance and Caching

Consuming Web APIs

After spending a lot of time building your shiny new Web API, it's time to jump over the fence and take a look at how people will consume it. In this module you will learn how .NET applications, as well as JavaScript applications can easily consume your Web API.

• Web APIs in Modern Web Development
• Consuming a Web API from .NET
• Best Practices for the .NET HttpClient
• Generating Client-side Code with Kiota
• Consuming a Web API from JavaScript with Fetch
• Web APIs and JavaScript Frameworks
• Cross-Origin Resource Sharing (CORS)
• LAB: Building a Client for your Web API

Async Web API Patterns

Real-time updates are no longer a "nice-to-have" feature. With the release of ASP.NET Core 10, we finally have a native, high-level API for Server-Sent Events (SSE). It bridges the gap between basic HTTP polling and full-duplex WebSockets via SignalR. We will also introduce a couple of patterns that allow you to decouple requests from their responses, so your clients don't get bogged down by your service.

• What are Server-Sent Events?
• Using Channels for SSE
• Using Hosted Services for Processing
• Replaying dropped events using OrderEventBuffer
• Async Request-Reply Pattern: decoupling Request and Response
• Webhooks: Events for the Web
• LAB: Adding Notifications using SSE

Testing

Every developer aspires to write code that is not only clean but also functional. However, achieving code that is easily maintainable and consistently operational poses a significant challenge. We will explore the role of unit testing in verifying the correctness of our code and ensuring its continued functionality.

• Finding Bugs
• What is Unit Testing
• Unit Tests versus Integration Tests
• Test Driven Development
• The AAA of Unit Testing
• Testing with Dependencies
• Stubs and Mocks

Testing for Web API

Testing a Web API brings its own challenges: your code is called by the framework, not by you. In this module you will apply what you learned to controllers, filters and Minimal API endpoints.

• Testing Controllers
• Testing Action Filters
• Testing Minimal APIs
• Integration Testing with WebApplicationFactory
• LAB: Dependency Injection and Testing in Web API