copilot-agentic-workshop api.instructions.md

API Endpoint Conventions

Endpoint Structure

Always register endpoints using the MapGroup + extension method pattern:

public static class FeatureEndpoints
{
    public static IEndpointRouteBuilder MapFeatureEndpoints(this IEndpointRouteBuilder routes)
    {
        var group = routes.MapGroup("/api/feature").WithTags("Feature");
        // ... endpoint registrations
        return routes;
    }
}

Then call app.MapFeatureEndpoints() from Program.cs.

HTTP Verb Mapping

Operation	Verb	Route
List all	GET	/api/{resource}
Get by ID	GET	/api/{resource}/{id:guid}
Create	POST	/api/{resource}
Partial update	PATCH	/api/{resource}/{id:guid}
State transition	POST	/api/{resource}/{id:guid}/{action}
Delete	DELETE	/api/{resource}/{id:guid}

Required Metadata on Every Endpoint

Every endpoint must have:

• .WithName("VerbResourceName") — e.g. "GetAllTasks", "CreateTask"
• .WithSummary("Human-readable description") — used by OpenAPI/Swagger

Response Types

Use Results.* helpers — never return IActionResult or raw status codes:

Results.Ok(dto)                          // 200
Results.CreatedAtRoute("Name", new { id }, dto)  // 201
Results.NoContent()                      // 204
Results.NotFound()                       // 404
Results.BadRequest("reason")             // 400

Input Binding

• Bind from body with [FromBody] for POST/PATCH payloads
• Bind route parameters directly in the lambda signature: (Guid id, ...)
• Always pass CancellationToken ct as the last lambda parameter

OpenAPI

• Use builder.Services.AddOpenApi() and app.MapOpenApi() in Program.cs
• Do not use the deprecated WithOpenApi() extension on individual endpoints