web-api
/web-api
Pomaga rozwijać kontrolerowe API ASP.NET Core z walidacją, OData, JsonPatch i wiązaniem modeli.
- Autor
- managedcode ↗
- Repozytorium
- dotnet-skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 26.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Pomaga rozwijać kontrolerowe API ASP.NET Core z walidacją, OData, JsonPatch i wiązaniem modeli.
Oryginalny opis (EN)
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
Jak działa
- Trigger On
- Workflow
- Current Upstream Notes
- Deliver
- Validate
- Controller Structure
- Model Binding
- Validation
- API Versioning
- Exception Handling
Podgląd SKILL.md
---
name: web-api
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."
compatibility: "Requires an ASP.NET Core API project that uses or should use controllers."
---
# 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:
```csharp
[ApiController]
[Route("api/[controller]")]
public class OrdersController(
IOrderService orderService,
ILogger<OrdersController> logger) : ControllerBase
{
[HttpGet("{id:guid}")]
[ProducesResponseType<OrderDto>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
{
var order = await orderService.GetByIdAsync(id, ct);
return order is null ? NotFound() : Ok(order);
}
[HttpPost]
[ProducesResponseType<OrderDto>(StatusCodes.Status201Created)]
[ProducesResponseType<ValidationProblemDetails>(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(CreateOrderRequest request, CancellationToken ct)
{
var order = await orderService.CreateAsync(request, ct);
return CreatedAtAction(nameof(GetById), new { id = order.Id }, order);
}
}
```
## Model Binding
Explicitly declare binding sources for clarity:
```csharp
[HttpGet("{id:guid}")]
public async Task<IActionResult> GetWithOptions(
[FromRoute] Guid id,
[FromQuery] bool includeDeleted = false,
[FromHeader(Name = "X-Correlation-Id")] string? correlationId = null,
CancellationToken ct = default)
{
// Route: id, Query: includeDeleted, Header: X-Correlation-Id
}
```
Use record types with required members for request DTOs:
```csharp
public record CreateProductRequest
{
public required string Name { get; init; }
public required decimal Price { get; init; }
public string? Description { get; init; }
public IReadOnlyList<string> Tags { get; init; } = [];
}
```
## Validation
Prefer FluentValidation for complex validation rules:
```csharp
public class CreateOrderRequestValidator : AbstractValidator<CreateOrderRequest>
{
public CreateOrderRequestValidator(IProductRepository products)
{
RuleFor(x => x.CustomerId)
.NotEmpty()
.WithMessage("Customer ID is required");
RuleFor(x => x.Items)
.NotEmpty()
.WithMessage("Order must contain at least one item");
RuleForEach(x => x.Items).ChildRules(item =>
{
item.RuleFor(i => i.ProductId)
.NotEmpty()
.MustAsync(async (id, ct) => await products.ExistsAsync(id, ct))
.WithMessage("Product does not exist");
item.RuleFor(i => i.Quantity)
.GreaterThan(0)
.LessThanOrEqualTo(100);
});
}
}
```
Configure consistent Problem Details responses:
```csharp
builder.Services.Configure<ApiBehaviorOptions>(options =>
{
options.InvalidModelStateResponseFactory = context =>
{
var problemDetails = new ValidationProblemDetails(context.ModelState)
{
Type = "https://tools.ietf.org/html/rfc7231#section-6.5.1",
Title = "One or more validation errors occurred.",
Status = StatusCodes.Status400BadRequest,
Instance = context.HttpContext.Request.Path
};
return new BadRequestObjectResult(problemDetails);
};
});
```
## API Versioning
Configure URL path versioning:
```csharp
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
.AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});
[ApiController]
[Route("api/v{version:apiVersion}/products")]
[ApiVersion("1.0")]
public class ProductsV1Controller(IProductService productService) : ControllerBase
{
[HttpGet("{id}")]
public async Task<IActionResult> Get(int id, CancellationToken ct)
{
var product = await productService.GetAsync(id, ct);
return Ok(product);
}
}
```
## Exception Handling
Use global exception handlers for consistent error responses:
```csharp
public class GlobalExceptionHandler(
ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
{
public async ValueTask<bool> TryHandleAsync(
HttpContext httpContext,
Exception exception,
CancellationToken cancellationToken)
{
logger.LogError(exception, "Unhandled exception occurred");
var problemDetails = exception switch
{
ValidationException validationEx => new ProblemDetails
{
Status = StatusCodes.Status400BadRequest,
Title = "Validation Error",
Detail = validationEx.Message
},
NotFoundException notFoundEx => new ProblemDetails
{
Status = StatusCodes.Status404NotFound,
Title = "Resource Not Found",
Detail = notFoundEx.Message
},
_ => new ProblemDetails
{
Status = StatusCodes.Status500InternalServerError,
Title = "Internal Server Error"
}
};
problemDetails.Extensions["traceId"] = httpContext.TraceIdentifier;
httpContext.Response.StatusCode = problemDetails.Status ?? 500;
await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);
return true;
}
}
```
## References
- [patterns.md](references/patterns.md) - Controller patterns, model binding, validation, versioning, response handling, and filter patterns
- [anti-patterns.md](references/anti-patterns.md) - Common API mistakes to avoid including fat controllers, inconsistent errors, missing cancellation tokens, and improper HTTP semantics
Pliki w paczce (4)
- SKILL.md 8 KB
- manifest.json 1 KB
- references/anti-patterns.md 21 KB
- references/patterns.md 17 KB
Wersje
W bazie nie ma innych skilli o nazwie web-api.
Migawka bazy z 13.11.2026 · wersja paczki 966c5603ca7f (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100minimal-apis
Projektuje i implementuje Minimal APIs w ASP.NET Core z endpointami zorientowanymi na handler, grupami tras i filtrami oraz pomaga wybrać między nimi a kontrolerami. - 100aspnet-core
Pomaga budować, debugować, modernizować i recenzować aplikacje ASP.NET Core z poprawnym hostingiem, middleware, bezpieczeństwem, konfiguracją, logowaniem i wdrażaniem na aktualnym .NET. - 85aspnet-core
Buduje, przegląda i refaktoryzuje aplikacje ASP.NET Core: Blazor, Razor Pages, MVC, Minimal API, SignalR, uwierzytelnianie i wydajność. - 100csharp-aspnet-core-web-api
Pomaga budować szybkie, wieloplatformowe REST API i minimalne API w C# na ASP.NET Core. - 90neo-dotnet-webapi
Pomaga budować, debugować i recenzować kontrolerowe Web API w ASP.NET Core: ControllerBase, ActionResult<T>, Problem Details, wersjonowanie API, globalną obsługę wyjątków, DTO i OpenAPI. - 100aspnet-core
Dostarcza zasady i dobre praktyki dla projektów ASP.NET Core: Minimal APIs, EF Core, uwierzytelnianie, middleware i wdrażanie.