Tworzenie interfejsów API w ASP.NET Core do niedawna kojarzyło się z rozbudowaną strukturą projektu – kontrolerami, klasą Startup, licznymi konfiguracjami. Jednak wraz z pojawieniem się .NET 6 zaprezentowano podejście Minimal API, które pozwala stworzyć działające API dosłownie w kilku linijkach kodu. W tym artykule wyjaśnię, czym jest Minimal API, pokaże prosty przykład jego użycia i omówię, kiedy warto z niego korzystać.
Czym jest Minimal API?
Minimal API to nowy styl tworzenia usług webowych HTTP w ASP.NET Core, wprowadzony w .NET 6. Wykorzystuje on możliwości C# 9 (instrukcje najwyższego poziomu), aby drastycznie uprościć kod potrzebny do uruchomienia aplikacji. Zamiast definiować kontrolery i wiele plików konfiguracyjnych, możemy zarejestrować endpointy bezpośrednio w kodzie aplikacji. Według dokumentacji Microsoftu minimal API zaprojektowano właśnie z myślą o tworzeniu HTTP API z minimalną ilością zależności. Są idealne dla mikroserwisów i aplikacji, które chcą zawierać tylko absolutne minimum plików, funkcji i zależności w ASP.NET Core. Innymi słowy – mniej ceremonii i narzutu, a więcej prostego kodu realizującego konkretne funkcje.
Jeśli korzystałeś wcześniej z Node.js (np. biblioteka Express) lub Python Flask, koncepcja będzie znajoma. W minimal API po prostu mapujemy adres URL na fragment kodu (funkcję/lambda), który ma zostać wykonany dla danego żądania, a następnie uruchamiamy aplikację. Całość mieści się często w jednym pliku (najczęściej Program.cs). To wciąż pełnoprawna aplikacja ASP.NET Core, ale o znacznie uproszczonej strukturze.
Przykład prostego minimal API
Poniżej znajduje się przykład minimalnej aplikacji API napisanej w C# przy użyciu minimal API. Ten kod tworzy prosty serwer HTTP i definiuje jeden endpoint HTTP GET:
/* Program.cs */
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/hello", () => "Witaj, świecie!");
app.Run();To wszystko – powyższy kod reprezentuje kompletną aplikację. Po uruchomieniu i przejściu w przeglądarce pod adres /hello, serwer zwróci tekst "Witaj, świecie!". Zwróć uwagę, że nie ma tutaj kontrolerów ani osobnej konfiguracji routingu. Wszystko odbywa się za pomocą wywołań na obiekcie app. Metoda MapGet rejestruje obsługę żądania GET pod wskazanym adresem URL (/hello) i przypisuje do niego funkcję anonimową zwracającą napis. Na końcu wywołujemy app.Run(), aby uruchomić aplikację w serwerze Kestrel.
Możemy łatwo rozszerzyć ten przykład o kolejne endpointy. Przykładowo, dodając poniższą linię, obsłużymy parametr ścieżki i pozdrowimy użytkownika po imieniu:
app.MapGet("/hello/{name}", (string name) => $"Witaj, {name}!");Dzięki takiej składni ASP.NET Core automatycznie pobierze wartość {name} z adresu URL i przekaże ją do funkcji jako argument. Widzimy więc, że nawet obsługa parametrów czy danych wejściowych jest możliwa w prosty sposób, bez dodatkowej konfiguracji.
Zalety minimal API
Minimal API w ASP.NET Core przynosi szereg korzyści, zwłaszcza w odpowiednich zastosowaniach:
• Minimalna ilość kodu i konfiguracji: Uruchomienie działającego API wymaga zaledwie kilku linijek kodu. Nie musimy tworzyć klas kontrolerów, opisywać tras ani budować całej struktury katalogów – szybki start nowego projektu jest dzięki temu dużo prostszy.
• Szybkie prototypowanie i mikroserwisy: Minimal API świetnie nadaje się do pisania małych usług oraz mikroserwisów. Gdy potrzebujesz szybko wystawić prosty endpoint lub zbudować prototyp API, to podejście pozwala skupić się na logice zamiast na ceremoniale. Taka usługa zawiera tylko to, co niezbędne, bez nadmiarowych elementów.
• Wyższa wydajność: Mniej warstw i abstrakcji oznacza potencjalnie mniejszy narzut. Otrzymujemy wydajność zbliżoną do pracy bezpośrednio na niskopoziomowym middleware, ale z zachowaniem wygody wysokopoziomowego frameworka.
• Przejrzystość (dla prostych scenariuszy): W przypadku niewielkich projektów cała logika jest widoczna w jednym miejscu, co ułatwia zrozumienie działania aplikacji. Nowi członkowie zespołu czy początkujący programiści mogą łatwiej pojąć, jak obsługiwane są żądania, bo wszystko jest tu "na wierzchu".
Minimal API – nie na każdą okazję
Oczywiście, Minimal API nie jest rozwiązaniem na wszystkie problemy. Im prostsze podejście, tym większe pojawiają się ograniczenia w miarę rozrostu aplikacji. W dużych projektach z dziesiątkami endpointów i złożoną logiką biznesową trzymanie wszystkiego w jednym pliku szybko stałoby się chaotyczne i trudne w utrzymaniu. Klasyczny podział na kontrolery, serwisy, repozytoria i pliki konfiguracji lepiej sprawdza się przy rozbudowanych aplikacjach, zapewniając wyraźną strukturę.
Minimal API warto więc stosować tam, gdzie jego atuty najbardziej błyszczą – w prostych API, mikroserwisach, narzędziach pomocniczych czy prototypach. W przypadku aplikacji o skomplikowanej domenie czy rozbudowanym interfejsie REST nadal lepiej sięgnąć po pełne podejście MVC (Model-View-Controller) lub rozważyć podejście mieszane (np. część endpointów jako minimal API, część jako kontrolery). Na szczęście wybór należy do nas – tradycyjne rozwiązanie wciąż jest dostępne i Microsoft nie zamierza go usuwać.
Podsumowanie
Minimal API to jedno z ciekawszych usprawnień w ekosystemie ASP.NET Core ostatnich lat. Pozwala na błyskawiczne tworzenie lekkich usług webowych, co otwiera .NET na scenariusze, w których do tej pory królowały bardziej "zwinnie" technologie jak Node.js. Dzięki minimal API programiści C# mogą stworzyć np. prosty backend dla aplikacji frontendowej lub usługę testową znacznie szybciej niż dawniej, nie rezygnując przy tym z zalet platformy .NET.
Warto samodzielnie spróbować napisać małe API w tym stylu – choćby dla nauki. Być może okaże się, że w wielu przypadkach to wystarczy zamiast pełnego projektu opartego na kontrolerach.
Na koniec, jeśli chcesz dalej rozwijać swoje umiejętności w ASP.NET Core – od podstaw po zaawansowane tematy (w tym omawiane Minimal API i wiele więcej) – zapraszam do mojego kompletnego szkolenia online Szkoła ASP.NET Core. To kompleksowe szkolenie, w którym krok po kroku budujemy nowoczesne aplikacje webowe w oparciu o platformę .NET Core. Dzięki niemu zdobędziesz praktyczną wiedzę i pewność w tworzeniu własnych projektów.
