coder-csharp-aspnetcore-api

<skill_overview> Build robust, performant, and well-documented ASP.NET Core APIs Creating new API endpoints Choosing Controllers vs Minimal APIs Setting up authentication/authorization Implementing caching or rate limiting Documenting APIs with OpenAPI Microsoft Web API Documentation </skill_overview> <controllers_vs_minimal> <use_controllers_when> Large applications with complex routing Need filters, model binding features Team prefers MVC structure Complex authorization with filters </use_controllers_when> <use_minimal_when> Microservices, small APIs Simple endpoints without much middleware Performance-critical scenarios Prefer less ceremony/boilerplate </use_minimal_when> <controller_example> [ApiController] [Route(“api/[controller]”)] public class UsersController : ControllerBase { private readonly IUserService _userService;

public UsersController(IUserService userService)
{
    _userService = userService;
}

[HttpGet("{id}")]
[ProducesResponseType(typeof(UserDto), 200)]
[ProducesResponseType(404)]
public async Task<ActionResult<UserDto>> GetById(int id)
{
    var user = await _userService.GetByIdAsync(id);
    return user == null ? NotFound() : Ok(user);
}

[HttpPost]
[ProducesResponseType(typeof(UserDto), 201)]
[ProducesResponseType(400)]
public async Task<ActionResult<UserDto>> Create(CreateUserDto dto)
{
    var user = await _userService.CreateAsync(dto);
    return CreatedAtAction(nameof(GetById), new { id = user.Id }, user);
}

} </controller_example> <minimal_example> var app = builder.Build(); var users = app.MapGroup(“/api/users”); users.MapGet(“/{id}”, async (int id, IUserService service) => await service.GetByIdAsync(id) is UserDto user ? TypedResults.Ok(user) : TypedResults.NotFound()) .WithName(“GetUserById”) .Produces<UserDto>(200) .Produces(404); users.MapPost(“/”, async (CreateUserDto dto, IUserService service) => { var user = await service.CreateAsync(dto); return TypedResults.Created($”/api/users/{user.Id}”, user); }) .WithName(“CreateUser”) .Produces<UserDto>(201); </minimal_example> </controllers_vs_minimal> <dtos_and_mapping> Never expose entities directly – always use DTOs Security: prevent over-posting attacks Decoupling: API contract independent of database Control: expose only needed fields <mapping_options> Fastest, explicit, most control Source-generated, fast, compile-time safe Faster than AutoMapper, good DX Most features, slower </mapping_options> // Entity (never expose directly) public class User { public int Id { get; set; } public string Email { get; set; } public string PasswordHash { get; set; } // Never expose! public DateTime CreatedAt { get; set; } } // DTOs (expose these) public record UserDto(int Id, string Email, DateTime CreatedAt); public record CreateUserDto(string Email, string Password); // Manual mapping public static UserDto ToDto(this User user) => new(user.Id, user.Email, user.CreatedAt); </dtos_and_mapping> <jwt_setup> builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.Authority = “https://your-auth-server“; options.Audience = builder.Configuration[“Auth:Audience”]; options.TokenValidationParameters = new TokenValidationParameters { ValidateIssuer = true, ValidateAudience = true, ValidateLifetime = true, ValidateIssuerSigningKey = true }; }); builder.Services.AddAuthorization(); app.UseAuthentication(); app.UseAuthorization(); </jwt_setup> <policy_authorization> // Define policies builder.Services.AddAuthorization(options => { options.AddPolicy(“AdminOnly”, policy => policy.RequireRole(“Admin”));

options.AddPolicy("CanEditOrders", policy =>
    policy.RequireClaim("Permission", "Orders.Edit"));

options.AddPolicy("MinAge18", policy =>
    policy.Requirements.Add(new MinimumAgeRequirement(18)));

}); // Apply to endpoints [Authorize(Policy = “AdminOnly”)] public IActionResult AdminAction() => Ok(); // Minimal API app.MapDelete(“/orders/{id}”, DeleteOrder) .RequireAuthorization(“CanEditOrders”); </policy_authorization> public record PagedResult<T>( IEnumerable<T> Items, int TotalCount, int Page, int PageSize) { public int TotalPages => (int)Math.Ceiling(TotalCount / (double)PageSize); public bool HasPrevious => Page > 1; public bool HasNext => Page < TotalPages; } [HttpGet] public async Task<ActionResult<PagedResult<UserDto>>> GetUsers( [FromQuery] int page = 1, [FromQuery] int pageSize = 10) { var query = _context.Users .AsNoTracking() .OrderBy(u => u.CreatedAt);

var totalCount = await query.CountAsync();

var items = await query
    .Skip((page - 1) * pageSize)
    .Take(pageSize)
    .Select(u => u.ToDto())
    .ToListAsync();

return Ok(new PagedResult<UserDto>(items, totalCount, page, pageSize));

} Always include OrderBy before Skip/Take <output_caching description=”.NET 7+”> builder.Services.AddOutputCache(options => { options.DefaultExpirationTimeSpan = TimeSpan.FromMinutes(5); }); app.UseOutputCache(); // Apply to endpoint app.MapGet(“/products”, GetProducts) .CacheOutput(p => p.Expire(TimeSpan.FromMinutes(10))); // With tag for invalidation app.MapGet(“/products/{id}”, GetProduct) .CacheOutput(p => p.Tag(“products”)); app.MapPost(“/products”, async (Product p, IOutputCacheStore cache) => { // Invalidate cache after create await cache.EvictByTagAsync(“products”, default); return Results.Created(); }); </output_caching> <response_caching> builder.Services.AddResponseCaching(); app.UseResponseCaching(); [HttpGet] [ResponseCache(Duration = 60, VaryByQueryKeys = new[] { “page” })] public IActionResult GetProducts() => Ok(); </response_caching> <rate_limiting description=”.NET 7+”> builder.Services.AddRateLimiter(options => { options.AddFixedWindowLimiter(“fixed”, opt => { opt.PermitLimit = 100; opt.Window = TimeSpan.FromMinutes(1); opt.QueueProcessingOrder = QueueProcessingOrder.OldestFirst; opt.QueueLimit = 10; });

options.AddSlidingWindowLimiter("sliding", opt =>
{
    opt.PermitLimit = 100;
    opt.Window = TimeSpan.FromMinutes(1);
    opt.SegmentsPerWindow = 4;
});

options.RejectionStatusCode = 429;

}); app.UseRateLimiter(); app.MapGet(“/api/resource”, GetResource) .RequireRateLimiting(“fixed”); </rate_limiting> <response_compression> builder.Services.AddResponseCompression(options => { options.EnableForHttps = true; options.Providers.Add<BrotliCompressionProvider>(); options.Providers.Add<GzipCompressionProvider>(); }); builder.Services.Configure<BrotliCompressionProviderOptions>(options => options.Level = CompressionLevel.Fastest); app.UseResponseCompression(); // Before endpoints </response_compression> builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(c => { c.SwaggerDoc(“v1”, new OpenApiInfo { Title = “My API”, Version = “v1”, Description = “API for managing resources” });

// Include XML comments
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

// JWT auth in Swagger
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
    Type = SecuritySchemeType.Http,
    Scheme = "bearer",
    BearerFormat = "JWT"
});

}); if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); } <xml_comments> /// <summary> /// Gets a user by ID /// </summary> /// <param name=”id”>The user identifier</param> /// <returns>The user or 404 if not found</returns> /// <response code=”200″>Returns the user</response> /// <response code=”404″>User not found</response> [HttpGet(“{id}”)] [ProducesResponseType(typeof(UserDto), 200)] [ProducesResponseType(404)] public async Task<ActionResult<UserDto>> GetById(int id) </xml_comments> <csproj_setting> <PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup> </csproj_setting> builder.Services.AddApiVersioning(options => { options.DefaultApiVersion = new ApiVersion(1, 0); options.AssumeDefaultVersionWhenUnspecified = true; options.ReportApiVersions = true; options.ApiVersionReader = ApiVersionReader.Combine( new UrlSegmentApiVersionReader(), new HeaderApiVersionReader(“X-Api-Version”)); }); // URL versioning [ApiController] [Route(“api/v{version:apiVersion}/[controller]”)] [ApiVersion(“1.0”)] [ApiVersion(“2.0”)] public class UsersController : ControllerBase { [HttpGet, MapToApiVersion(“1.0”)] public IActionResult GetV1() => Ok(“v1”);

[HttpGet, MapToApiVersion("2.0")]
public IActionResult GetV2() => Ok("v2");

}