dotnet-webapi

# .NET 10 Web API Development

Build production-ready ASP.NET Core Web APIs with .NET 10 using best practices from 2025.

## Quick Start

Create a new Web API project:

```bash
scripts/new_api.sh <project_name> [output_directory]
```

**Example:**
```bash
scripts/new_api.sh ProductsApi
cd ProductsApi
dotnet build
dotnet run --project ProductsApi.Api
```

This creates:
- Solution with API and Test projects
- Controller-based Web API (.NET 10)
- xUnit test project with integration testing setup
- Proper folder structure (Controllers, Models, Services)
- .gitignore configured for .NET

---

## Core Features

### 1. Project Scaffolding

**Create New API Project:**
```bash
scripts/new_api.sh MyApi ./projects
```

Generates:
- `MyApi.Api` - Main API project with controllers
- `MyApi.Tests` - xUnit test project with integration testing
- Solution file linking both projects
- Standard folder structure
- Test dependencies (FluentAssertions, WebApplicationFactory)

### 2. Add CRUD Entities

**Generate Entity with Controller and Service:**
```bash
scripts/add_entity.sh <entity_name> <project_path>
```

**Example:**
```bash
scripts/add_entity.sh Product ./MyApi
scripts/add_entity.sh Customer ./MyApi
```

Generates for each entity:
- Model class (`Models/Product.cs`)
- Service interface (`Services/IProductService.cs`)
- Service implementation (`Services/ProductService.cs`)
- CRUD controller (`Controllers/ProductController.cs`)
- Automatic service registration in DI container

**API Endpoints Created:**
```
GET    /api/Product        - Get all
GET    /api/Product/{id}   - Get by ID
POST   /api/Product        - Create
PUT    /api/Product/{id}   - Update
DELETE /api/Product/{id}   - Delete
```

### 3. Package Management

**Add NuGet Packages:**
```bash
scripts/add_package.sh <project_path> <package_name|preset>
```

**Presets:**
```bash
# Entity Framework with PostgreSQL
scripts/add_package.sh ./MyApi ef-postgres

# Entity Framework with SQL Server
scripts/add_package.sh ./MyApi ef-sqlserver

# JWT Authentication
scripts/add_package.sh ./MyApi auth

# FluentValidation
scripts/add_package.sh ./MyApi validation

# Individual package
scripts/add_package.sh ./MyApi Newtonsoft.Json
```

### 4. Docker Support

**Generate Dockerfile and docker-compose:**
```bash
scripts/generate_dockerfile.sh <project_path>
```

**Example:**
```bash
scripts/generate_dockerfile.sh ./MyApi
```

Generates:
- Multi-stage optimized Dockerfile
- docker-compose.yml with PostgreSQL
- .dockerignore
- Non-root user configuration
- Health check setup

**Build and run:**
```bash
docker-compose up -d
docker-compose logs -f api
```

---

## .NET 10 Features

### Built-in Features

**OpenAPI 3.1 Support:**
```csharp
// Program.cs
builder.Services.AddOpenApi();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi(); // /openapi/v1.json
}
```

**Automatic Minimal API Validation:**
DataAnnotations are automatically validated in .NET 10 for Minimal APIs and controllers.

**Output Caching:**
```csharp
builder.Services.AddOutputCache();
app.UseOutputCache();

[OutputCache(Duration = 300)]
[HttpGet]
public async Task<IActionResult> GetAll()
```

**Rate Limiting:**
```csharp
builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("api", config =>
    {
        config.PermitLimit = 100;
        config.Window = TimeSpan.FromMinutes(1);
    });
});
```

### C# 14.0 Features

Use latest C# features:
- Primary constructors
- Collection expressions
- Required members
- Init-only properties

---

## Development Workflows

### Typical Development Flow

1. **Create project:**
   ```bash
   scripts/new_api.sh OrderService
   cd OrderService
   ```

2. **Add entities:**
   ```bash
   scripts/add_entity.sh Order .
   scripts/add_entity.sh OrderItem .
   ```

3. **Add database:**
   ```bash
   scripts/add_package.sh . ef-postgres
   ```

4. **Build and run:**
   ```bash
   dotnet build
   dotnet run --project OrderService.Api
   ```

5. **Test:**
   ```bash
   dotnet test
   ```

6. **Dockerize:**
   ```bash
   scripts/generate_dockerfile.sh .
   docker-compose up
   ```

### Entity Framework Integration

After adding EF packages, configure DbContext:

```csharp
// Data/ApplicationDbContext.cs
public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options) { }

    public DbSet<Product> Products => Set<Product>();
}

// Program.cs
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));

// appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=mydb;Username=postgres;Password=postgres"
  }
}
```

**Run migrations:**
```bash
dotnet ef migrations add Initial --project MyApi.Api
dotnet ef database update --project MyApi.Api
```

### Authentication Setup

After adding auth package:

```csharp
// Program.cs
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]))
        };
    });

app.UseAuthentication();
app.UseAuthorization();

// Protect endpoints
[Authorize]
[HttpGet("admin")]
public IActionResult AdminOnly() => Ok("Admin data");
```

---

## Best Practices

### Controller Pattern

Generated controllers follow best practices:

```csharp
[ApiController]
[Route("api/[controller]")]
public class ProductController : ControllerBase
{
    private readonly IProductService _service;
    private readonly ILogger<ProductController> _logger;

    // Constructor injection
    public ProductController(
        IProductService service,
        ILogger<ProductController> logger)
    {
        _service = service;
        _logger = logger;
    }

    // Documented endpoints
    /// <summary>
    /// Get all products
    /// </summary>
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public async Task<ActionResult<IEnumerable<Product>>> GetAll()

    // Proper status codes
    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task<ActionResult<Product>> Create(Product entity)
    {
        var created = await _service.CreateAsync(entity);
        return CreatedAtAction(nameof(GetById), new { id = created.Id }, created);
    }
}
```

### Service Layer Pattern

```csharp
// Interface
public interface IProductService
{
    Task<IEnumerable<Product>> GetAllAsync();
    Task<Product?> GetByIdAsync(int id);
    Task<Product> CreateAsync(Product entity);
    Task<Product?> UpdateAsync(int id, Product entity);
    Task<bool> DeleteAsync(int id);
}

// Implementation with business logic
public class ProductService : IProductService
{
    // In-memory for demo, replace with repository/DbContext
    private readonly List<Product> _entities = new();

    public async Task<Product> CreateAsync(Product entity)
    {
        entity.Id = _nextId++;
        entity.CreatedAt = DateTime.UtcNow;
        _entities.Add(entity);
        return entity;
    }
}
```

---

## Testing

Generated test projects include integration testing setup:

```csharp
public class ProductsEndpointTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public ProductsEndpointTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task GetAll_ReturnsSuccessStatusCode()
    {
        var response = await _client.GetAsync("/api/products");
        response.EnsureSuccessStatusCode();
    }
}
```

**Run tests:**
```bash
dotnet test
dotnet test --logger "console;verbosity=detailed"
```

---

## References

For detailed guidance, see:

### API Best Practices
`references/api_best_practices.md` - Comprehensive guide covering:
- RESTful API design
- HTTP status codes
- Error handling patterns
- Validation strategies
- Authentication & authorization
- Dependency injection
- Logging best practices
- Performance optimization
- OpenAPI documentation

### Testing Patterns
`references/testing_patterns.md` - Testing guide including:
- xUnit fundamentals
- Unit testing with Moq
- Integration testing with WebApplicationFactory
- Test data builders
- FluentAssertions usage
- Common testing patterns

### Common Packages
`references/common_packages.md` - NuGet package guide for:
- Database providers (EF Core, Dapper)
- Authentication (JWT, Identity)
- Validation (FluentValidation)
- Testing tools (xUnit, Moq, FluentAssertions)
- Logging (Serilog)
- Utilities (AutoMapper, MediatR, Polly)

---

## Common Scenarios

### Scenario 1: New CRUD API

```bash
# Create project
scripts/new_api.sh InventoryApi

# Add entities
scripts/add_entity.sh Product ./InventoryApi
scripts/add_entity.sh Category ./InventoryApi

# Add database
scripts/add_package.sh ./InventoryApi ef-postgres

# Run
cd InventoryApi
dotnet run --project InventoryApi.Api
```

### Scenario 2: Microservice with Docker

```bash
# Create and setup
scripts/new_api.sh OrderService
scripts/add_entity.sh Order ./OrderService
scripts/add_package.sh ./OrderService ef-postgres
scripts/generate_dockerfile.sh ./OrderService

# Deploy
cd OrderService
docker-compose up -d
```

### Scenario 3: Authenticated API

```bash
scripts/new_api.sh SecureApi
scripts/add_entity.sh User ./SecureApi
scripts/add_package.sh ./SecureApi auth
scripts/add_package.sh ./SecureApi validation
```

---

## Troubleshooting

### .NET SDK Not Found

Ensure .NET 10 SDK is installed:
```bash
dotnet --version  # Should be 10.x
```

Install from: https://dotnet.microsoft.com/download/dotnet/10.0

### Port Already in Use

Change port in Properties/launchSettings.json or use environment variable:
```bash
ASPNETCORE_HTTP_PORTS=5001 dotnet run --project MyApi.Api
```

### Docker Build Fails

Ensure Docker daemon is running:
```bash
docker ps
```

Check Dockerfile paths match project structure.

### EF Migrations Fail

Ensure connection string is correct and database is accessible:
```bash
dotnet ef database update --verbose --project MyApi.Api
```

---

## Integration with Other Skills

Works well with:
- `postgres-query` - Query databases created by your API
- `postgres-backup-restore` - Restore test data for development
- `ruby-rails` - Interop with Rails backends

---

## Summary

This skill provides:

✅ Rapid project scaffolding
✅ CRUD entity generation
✅ NuGet package management
✅ Docker containerization
✅ .NET 10 best practices
✅ Testing setup included
✅ Production-ready code structure
✅ Comprehensive documentation

Start building modern Web APIs with .NET 10 today!