# Web API

Build or maintain controller-based ASP.NET Core APIs when the project needs controller...

- Repository: https://github.com/managedcode/dotnet-skills (500 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add managedcode/dotnet-skills --skill web-api -g -a claude-code -y`
Codex: `npx skills add managedcode/dotnet-skills --skill web-api -g -a codex -y`
Cursor: `npx skills add managedcode/dotnet-skills --skill web-api -g -a cursor -y`
Gemini CLI: `npx skills add managedcode/dotnet-skills --skill web-api -g -a gemini-cli -y`

## Description

Build or maintain controller-based ASP.NET Core APIs when the project needs controller conventions, advanced model binding, validation extensions, OData, JsonPatch, or existing API patterns. USE FOR: working on controller-based APIs in ASP.NET Core; needing controller-specific extensibility or conventions; migrating or reviewing existing API controllers and filters. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# ASP.NET Core Web API

## Trigger On

- working on controller-based APIs in ASP.NET Core
- needing controller-specific extensibility or conventions
- migrating or reviewing existing API controllers and filters

## Workflow

1. Use controllers when the API needs controller-centric features, not simply because older templates did so.
2. Keep controllers thin: map HTTP concerns to application services or handlers, and avoid embedding data access and business rules directly in actions.
3. Use clear DTO boundaries, explicit validation, and predictable HTTP status behavior.
4. Review authentication and authorization at both controller and endpoint levels so the API surface is not accidentally inconsistent.
5. Keep OpenAPI generation, versioning, and error contract behavior deliberate rather than incidental.
6. Use `minimal-apis` for new simple APIs instead of defaulting to controllers out of habit.

## Current Upstream Notes

- `dotnet/aspnetcore` `v10.0.11` is servicing and updates the OpenAPI stack to `2.7.5`; controller-based API guidance still depends on conventions, advanced model binding, OData, JsonPatch, and existing filters. Re-run generated-document and client contract checks after upgrading.
- The August 2026 `aspnetcore-10.0` overview keeps controller APIs alongside Minimal APIs rather than replacing them. Use the dedicated routing, OpenAPI, auth, and hosting pages before changing public API contracts.

## Deliver

- controller APIs with explicit contracts and policies
- reduced controller bloat
- tests or smoke checks for critical API behavior

## Validate

- controller features are actually justified
- actions do not hide business logic and persistence details
- HTTP semantics stay predictable across endpoints

## Controller Structure

Use primary constructors (C# 12+) for dependency injection and keep controllers focused on HTTP concerns:

The rest: https://github.com/managedcode/dotnet-skills/blob/HEAD/catalog/Frameworks/Web-API/skills/web-api/SKILL.md