ASP.NET Core - REST API s Minimal API krok za krokom

Minimal API je spôsob, ako v ASP.NET Core napísať webové API bez kontrolérov – celé API sa zmestí do jedného súboru Program.cs. Hodí sa na menšie služby, mikroslužby a na backend pre aplikácie v Reacte, Angulare či mobilné aplikácie.

V návode postavíme API pre správu úloh (todo list) s databázou SQLite: čítanie, vytváranie, úpravu aj mazanie záznamov.

Vytvorenie projektu

Potrebujete .NET SDK 8 alebo novší:

dotnet new web -n UlohyApi
cd UlohyApi
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet run

Šablóna web vytvorí prázdnu aplikáciu, ktorá na adrese uvedenej v konzole vráti text „Hello World!“. Celý jej kód je v Program.cs:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Model a databázový kontext

Na konci Program.cs (za app.Run()) doplňte triedy:

public class Uloha
{
    public int Id { get; set; }
    public string Nazov { get; set; } = "";
    public bool Hotova { get; set; }
    public DateTime Vytvorena { get; set; } = DateTime.UtcNow;
}

public record UlohaVstup(string Nazov, bool Hotova);

public class UlohyDb(DbContextOptions<UlohyDb> options) : DbContext(options)
{
    public DbSet<Uloha> Ulohy => Set<Uloha>();
}

Záznam UlohaVstup obsahuje iba to, čo smie poslať klient. Keby API prijímalo priamo triedu Uloha, klient by si mohol nastaviť aj Id či dátum vytvorenia.

Registrácia služieb

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<UlohyDb>(o => o.UseSqlite("Data Source=ulohy.db"));

var app = builder.Build();

// Pri štarte vytvorí databázu, ak neexistuje (na produkciu použite migrácie)
using (var scope = app.Services.CreateScope())
{
    scope.ServiceProvider.GetRequiredService<UlohyDb>().Database.EnsureCreated();
}

Endpointy

Endpointy zoskupíme pod spoločnú cestu /api/ulohy. Parametre metód (databázový kontext, ID z adresy, telo požiadavky) ASP.NET Core doplní sám:

var ulohy = app.MapGroup("/api/ulohy");

// GET /api/ulohy?hotove=false
ulohy.MapGet("/", async (UlohyDb db, bool? hotove) =>
{
    var dotaz = db.Ulohy.AsNoTracking();

    if (hotove is not null)
        dotaz = dotaz.Where(u => u.Hotova == hotove);

    return await dotaz.OrderBy(u => u.Vytvorena).ToListAsync();
});

// GET /api/ulohy/5
ulohy.MapGet("/{id:int}", async (int id, UlohyDb db) =>
    await db.Ulohy.FindAsync(id) is Uloha u
        ? Results.Ok(u)
        : Results.NotFound());

// POST /api/ulohy
ulohy.MapPost("/", async (UlohaVstup vstup, UlohyDb db) =>
{
    if (string.IsNullOrWhiteSpace(vstup.Nazov))
    {
        return Results.ValidationProblem(new Dictionary<string, string[]>
        {
            ["nazov"] = ["Názov úlohy je povinný."]
        });
    }

    var uloha = new Uloha { Nazov = vstup.Nazov.Trim(), Hotova = vstup.Hotova };
    db.Ulohy.Add(uloha);
    await db.SaveChangesAsync();

    return Results.Created($"/api/ulohy/{uloha.Id}", uloha);
});

// PUT /api/ulohy/5
ulohy.MapPut("/{id:int}", async (int id, UlohaVstup vstup, UlohyDb db) =>
{
    var uloha = await db.Ulohy.FindAsync(id);
    if (uloha is null) return Results.NotFound();

    uloha.Nazov = vstup.Nazov.Trim();
    uloha.Hotova = vstup.Hotova;
    await db.SaveChangesAsync();

    return Results.NoContent();
});

// DELETE /api/ulohy/5
ulohy.MapDelete("/{id:int}", async (int id, UlohyDb db) =>
{
    int zmazanych = await db.Ulohy.Where(u => u.Id == id).ExecuteDeleteAsync();
    return zmazanych == 1 ? Results.NoContent() : Results.NotFound();
});

app.Run();

Každá operácia vracia stavový kód, ktorý zodpovedá konvenciám REST:

OperáciaÚspechChyba
GET zoznam200 OK–
GET jeden záznam200 OK404 Not Found
POST201 Created + hlavička Location400 Bad Request (validácia)
PUT204 No Content404 Not Found
DELETE204 No Content404 Not Found

Obmedzenie {id:int} v ceste zabezpečí, že adresa /api/ulohy/abc skončí chybou 404 a do metódy sa vôbec nedostane.

Vyskúšanie

Visual Studio aj VS Code (s rozšírením REST Client) vedia spúšťať požiadavky zo súboru .http. Port nahraďte tým, ktorý vypísal dotnet run:

@api = http://localhost:5000/api/ulohy

### Vytvorenie úlohy
POST {{api}}
Content-Type: application/json

{ "nazov": "Napísať článok o Minimal API", "hotova": false }

### Zoznam nehotových úloh
GET {{api}}?hotove=false

### Označenie úlohy ako hotovej
PUT {{api}}/1
Content-Type: application/json

{ "nazov": "Napísať článok o Minimal API", "hotova": true }

### Zmazanie
DELETE {{api}}/1

Rovnako dobre poslúži curl:

curl -X POST http://localhost:5000/api/ulohy -H "Content-Type: application/json" -d "{\"nazov\":\"Test\",\"hotova\":false}"

CORS – volanie z inej domény

Ak API volá frontend bežiaci na inej adrese (napríklad React na http://localhost:5173), prehliadač požiadavku zablokuje, kým ju server výslovne nepovolí:

builder.Services.AddCors(o => o.AddDefaultPolicy(p => p
    .WithOrigins("http://localhost:5173")
    .AllowAnyHeader()
    .AllowAnyMethod()));

var app = builder.Build();

app.UseCors();

Nepovoľujte AllowAnyOrigin() na produkčnom API, ktoré pracuje s prihlásenými používateľmi – uveďte konkrétne domény svojho frontendu.

Dokumentácia OpenAPI

Od .NET 9 obsahuje ASP.NET Core vlastný generátor popisu API. Pridajte balík a dva riadky:

dotnet add package Microsoft.AspNetCore.OpenApi
builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();   // popis API na /openapi/v1.json
}

Súbor /openapi/v1.json viete načítať do nástrojov ako Postman alebo Scalar a nechať si z neho vygenerovať aj klienta pre frontend. V .NET 8 rovnakú úlohu plní balík Swashbuckle.AspNetCore.

Kedy prejsť na kontroléry

Minimal API nie je „menej výkonná“ verzia – je rovnako rýchla a podporuje autentifikáciu, filtre aj validáciu. Keď však endpointov pribúda, rozdeľte ich do statických tried s rozširujúcimi metódami (napr. app.MapUlohy()), aby Program.cs nenarástol na stovky riadkov. Kontroléry dávajú zmysel najmä vo veľkých projektoch, kde tím už na ne je zvyknutý.

Zhrnutie

  • MapGet, MapPost, MapPut, MapDelete definujú endpointy, MapGroup ich zoskupí pod spoločnú cestu.
  • Parametre (služby, hodnoty z cesty, telo) sa doplnia automaticky.
  • Vstup od klienta prijímajte cez samostatný typ, nie cez entitu databázy.
  • Vracajte správne stavové kódy cez Results.
  • Pre frontend na inej doméne nastavte CORS.
O autorovi

Ing.Jaroslav Vadel

Som zakladateľom www.projectik.eu. Hrám sa na programátora, ktorý ovláda: c#,cpp,java,unity3d,php,html,NI testand,NI Vision Builder,Cognex In-Sight,NI LabView "Naprogramovať program, ktorý funguje vie každy. Ale to, že program funguje ešte neznamena, že je napísany správne "

Súvisiace články