plan-forge api-patterns.instructions.md

.NET API Patterns

REST Conventions

Controller Structure

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class ProducersController(IProducerService service) : ControllerBase
{
    [HttpGet]
    public async Task<ActionResult<PagedResult<ProducerDto>>> GetAll(
        [FromQuery] int page = 1, [FromQuery] int pageSize = 25, CancellationToken ct = default)
    {
        var result = await service.GetPagedAsync(page, pageSize, ct);
        return Ok(result);
    }

    [HttpGet("{id:guid}")]
    public async Task<ActionResult<ProducerDto>> GetById(Guid id, CancellationToken ct = default)
    {
        var producer = await service.GetByIdAsync(id, ct);
        return producer is null ? NotFound() : Ok(producer);
    }

    [HttpPost]
    public async Task<ActionResult<ProducerDto>> Create(
        [FromBody] CreateProducerRequest request, CancellationToken ct = default)
    {
        var created = await service.CreateAsync(request, ct);
        return CreatedAtAction(nameof(GetById), new { id = created.Id }, created);
    }

    [HttpPut("{id:guid}")]
    public async Task<IActionResult> Update(
        Guid id, [FromBody] UpdateProducerRequest request, CancellationToken ct = default)
    {
        await service.UpdateAsync(id, request, ct);
        return NoContent();
    }

    [HttpDelete("{id:guid}")]
    public async Task<IActionResult> Delete(Guid id, CancellationToken ct = default)
    {
        await service.DeleteAsync(id, ct);
        return NoContent();
    }
}

Error Responses (ProblemDetails — RFC 9457)

// Automatic via app.UseExceptionHandler + ProblemDetails
builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
    };
});

// Manual ProblemDetails
return Problem(
    title: "Producer not found",
    detail: $"No producer with ID {id} exists",
    statusCode: StatusCodes.Status404NotFound,
    type: "https://tools.ietf.org/html/rfc9110#section-15.5.5");