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 | Úspech | Chyba |
|---|---|---|
| GET zoznam | 200 OK | – |
| GET jeden záznam | 200 OK | 404 Not Found |
| POST | 201 Created + hlavička Location | 400 Bad Request (validácia) |
| PUT | 204 No Content | 404 Not Found |
| DELETE | 204 No Content | 404 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,MapDeletedefinujú endpointy,MapGroupich 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.