description: Add a new minimal API endpoint to NovaTune with service, models, and tests

Add API Endpoint Skill

Add a new minimal API endpoint to NovaTune.

Steps

1. Create/Update Request and Response Models

Location: src/NovaTuneApp/NovaTuneApp.ApiService/Models/

// Models/Requests/CreateTrackRequest.cs
public record CreateTrackRequest(
    string Title,
    string? Description);

// Models/Responses/TrackResponse.cs
public record TrackResponse(
    Guid Id,
    string Title,
    string? Description,
    DateTimeOffset CreatedAt);

2. Create/Update Service

Location: src/NovaTuneApp/NovaTuneApp.ApiService/Services/

public interface ITrackService
{
    Task<Track> CreateAsync(CreateTrackRequest request, CancellationToken ct);
}

public class TrackService : ITrackService
{
    private readonly IDocumentSession _session;

    public TrackService(IDocumentSession session)
    {
        _session = session;
    }

    public async Task<Track> CreateAsync(CreateTrackRequest request, CancellationToken ct)
    {
        var track = new Track
        {
            Title = request.Title,
            Description = request.Description,
            CreatedAt = DateTimeOffset.UtcNow
        };

        await _session.StoreAsync(track, ct);
        await _session.SaveChangesAsync(ct);

        return track;
    }
}

3. Create Endpoint Group

Location: src/NovaTuneApp/NovaTuneApp.ApiService/Endpoints/

public static class TrackEndpoints
{
    public static void MapTrackEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/tracks")
            .WithTags("Tracks")
            .WithOpenApi();

        group.MapPost("/", CreateTrack)
            .WithName("CreateTrack")
            .RequireAuthorization();

        group.MapGet("/{id:guid}", GetTrack)
            .WithName("GetTrack");
    }

    private static async Task<IResult> CreateTrack(
        CreateTrackRequest request,
        ITrackService trackService,
        CancellationToken ct)
    {
        var track = await trackService.CreateAsync(request, ct);
        return TypedResults.Created($"/api/tracks/{track.Id}", track.ToResponse());
    }

    private static async Task<IResult> GetTrack(
        Guid id,
        ITrackService trackService,
        CancellationToken ct)
    {
        var track = await trackService.GetByIdAsync(id, ct);
        return track is null
            ? TypedResults.NotFound()
            : TypedResults.Ok(track.ToResponse());
    }
}

4. Register in Program.cs

// Register service
builder.Services.AddScoped<ITrackService, TrackService>();

// Map endpoints (after app.Build())
app.MapTrackEndpoints();

5. Add Tests

Unit test: src/unit_tests/TrackServiceTests.cs Integration test: src/NovaTuneApp/NovaTuneApp.Tests/TrackEndpoints.IntegrationTests.cs

Conventions

• Use minimal APIs with MapGroup
• Return TypedResults for proper OpenAPI schema
• Use WithTags and WithOpenApi for Scalar documentation
• Add RequireAuthorization() for protected endpoints
• Use CancellationToken in all async methods
• PascalCase for endpoint names

Response Status Codes

API Documentation

Access Scalar UI at /scalar/v1 when running the API.