Door de jaren heen zijn er naast doorontwikkeling van bestaande technologieën veel nieuwe mogelijkheden beschikbaar gekomen op het gebied van webontwikkeling en dan met name het ontwikkelen van HTTP API’s. Met de komst van ASP.NET Core is er een belangrijke nieuwe technologie beschikbaar gekomen: Minimal API’s, een eenvoudigere en efficiëntere manier om met minimale afhankelijkheden en minder ceremonies HTTP API’s te bouwen.
In dit artikel zullen we antwoord geven op de volgende vragen:
- Zijn Minimal API’s de silver bullit?
- Zijn Minimal API’s slechts geschikt om proof of concepts te maken?
- Moeten Minimal API’s vermeden worden in een productie omgeving?
Wat zijn Minimal API’s?
Minimal API’s zijn de tegenhanger van controller-based HTTP API’s. Het is een nieuwe functionaliteit in ASP.NET Core die het proces van het bouwen van deze API’s vereenvoudigt. Op die manier kunnen ontwikkelaars sneller en met minimale overhead HTTP API’s ontwikkelen.
Met Minimal API’s kunnen software developers HTTP API’s bouwen met slechts een paar regels code waardoor het ontwikkelproces sneller en eenvoudiger wordt. Het doel van deze nieuwe technologie is om de complexiteit van het bouwen van API’s te verminderen en het daardoor voor ontwikkelaars gemakkelijker te maken om snel aan de slag te gaan met het opzetten en ontwikkelen van endpoints.
Oké, klinkt goed, maar hoe ziet zo’n Minimal API er dan eigenlijk uit? De volgende code snippet laat zien hoe in 4 regels code een werkend voorbeeld van een HTTP API wordt opgezet:
En that’s it: in slechts 4 regels code hebben we een werkend voorbeeld van de REST API. Geen onnodig gebruik van usings, geen controllers, alles in slechts één file: de progam.cs file. Als opmerking moet worden toegevoegd dat hiervoor gebruik wordt gemaakt van Visual Studio 2022 en .NET 6 of hoger. Analoog aan bovenstaande code snippet kunnen we deze uitbreiden met andere meest gebruikte REST API calls:
Een Minimal API bestaat dus uit een aantal HTTP methoden met ieder 2 parameters: de endpoint route en een delegate functie die het HTTP request afhandelt.
Minimal API’s versus controller-based API’s
Zoals eerder vermeld zijn Minimal API’s de tegenhanger van controller-based HTTP API’s. Het belangrijkste verschil tussen minimal API’s en controllers is de manier waarop ze zijn ontworpen en hoe ze werken.
Controller-based API’s zijn onderdeel van het traditionele MVC (Model-View-Controller) patroon en bevatten de logica voor het verwerken van HTTP requests. Dit betekent dat ze onder water het volledige MVC framework en pipelines van ASP.NET meekrijgen. Minimal API’s zijn voornamelijk “synthetic sugar” waarbij optimalisaties op de routing zijn toegepast omdat de minimal api enkel voor api purposes gebruikt wordt.
Minimal API’s zijn ontworpen als een lightweight alternatief voor controller-based API’s en zijn bedoeld om eenvoudige RESTful API’s te maken zonder de extra overhead van de traditionele MVC-architectuur. In plaats van dat er een aparte controller nodig is voor elk HTTP request, bevatten minimal API’s slechts één enkele methode die wordt gebruikt om HTTP requests af te handelen en te reageren op basis van de inhoud van het request.
Een ander verschil is de manier waarop routing werkt. In traditionele controller-based API’s is het mogelijk om de routing op basis van controller naam en method name te doen (wat overigens in de praktijk eigenlijk weinig toegepast wordt), terwijl minimal API’s routing bepalen op basis van de HTTP-methode en de bijbehorende endpoint, die wordt gedefinieerd in de code.
Minimal API’s en controller-based API’s zijn beide manieren om een RESTful API te maken in C#, maar er zijn enkele belangrijke verschillen tussen beide technologieën:
- Code-structuur: bij het maken van controller-based API’s moet je een hiërarchische structuur creëren voor de gewenste endpoints en acties, terwijl bij het gebruik van minimal API’s alles binnen één enkel bestand blijft
- Routing: met minimal API’s moet je de routes van de endpoints expliciet definiëren.
- Minder overhead: Minimal API’s zijn ontworpen om minder overhead te hebben dan traditionele controller-based API’s, waardoor ze sneller kunnen werken en minder code vereisen
- Eenvoudiger: Minimal API’s zijn over het algemeen eenvoudiger in gebruik dan controller-based API’s, omdat ze minder configuratie en minder boiler-plate code vereisen
- Flexibiliteit: controller-based API’s zijn over het algemeen flexibeler in het ondersteunen van meer complexe routing en aanpassingsopties, terwijl Minimal API’s meer geschikt zijn voor kleinere projecten en minder complexe API’s
Het belangrijkste verschil tussen minimal API’s en controller-based API’s zit hem dus in de aanpak die je kiest om een RESTful API te creëren. Minimal API’s zijn ontworpen om eenvoudige, lightweight RESTful API’s te maken waar controller-based API’s worden gebruikt voor het afhandelen van HTTP-verzoeken in een (volledigere) MVC-architectuur.
Waarom Minimal API’s gebruiken?
Het gebruik van Minimal API’s heeft verschillende voordelen boven het gebruik van controller-based API’s. Ten eerste zijn ze eenvoudig en gebruiksvriendelijk. In tegenstelling tot traditionele controller-based API’s vereisen Minimale API’s (zoals de naam al suggereert) minimale code en kunnen ze snel worden gemaakt.
Daarnaast bieden Minimal API’s een betere/hogere performance dan traditionele controller-based API’s. Omdat ze minder overhead nodig hebben, zijn ze sneller en efficiënter. Dit is vooral belangrijk voor webapplicaties die een groot aantal HTTP requests moeten verwerken.
Er zijn dus verschillende redenen waarom het te overwegen is om Minimal API’s te gaan gebruiken als je (REST) API’s wilt gaan ontwikkelen:
- Eenvoud: Minimal API’s zijn ontworpen om eenvoudig en makkelijk in gebruik te zijn. Er is weinig boiler-plate code nodig om Minimal API’s op te zetten wat resulteert in het snel kunnen opzetten van endpoints.
- Performance: Minimal API’s bieden een betere performance dan traditionele controller-based API’s omdat ze minder overhead hebben. Dit maakt ze ideaal voor webapplicaties die een groot aantal requests moeten afhandelen.
- Proof of Concept: vanwege de eenvoud is het makkelijk om snel een simpele CRUD API te maken ten behoeve van prototyping e.d.
- Volledige ondersteuning van het .NET Core framework waardoor je altijd later kunt uitbreiden met controllers.
- Tot slot vormen Minimal API’s een goede basis voor het ontwikkelen binnen een microservices architectuur.
Samenvattend kunnen we stellen dat, als we snel, efficiënt en high-performance webapplicaties en API’s willen bouwen, Minimal API’s zeker het overwegen waard zijn. Ze bieden een eenvoudigere en flexibelere benadering voor het bouwen van API’s die kunnen helpen projecten sneller en met minder code te ontwikkelen.
Waarom géén Minimal API’s gebruiken?
Zijn Minimal API’s de silver bullet? Nee, dat is zeker niet het geval. Het biedt een andere manier voor het schrijven van HTTP REST API’s naast de al bestaande mogelijkheid met behulp van controller-based API’s.
Zo zijn er een aantal redenen te bedenken waarom je juist géén Minimal API’s wilt gebruiken:
- Complexiteit: hoewel Minimal API’s ontworpen zijn om simpeler te zijn dan traditionele API’s, kan het voor sommige ontwikkelaars een uitdaging zijn om te werken met de minder gestructureerde en meer flexibele aanpak van Minimal API’s. Daarnaast gaat bij gebruik van een groot aantal API’s het overzicht al snel verloren, waar dit bij controller based API’s door het gebruik van controllers gestructureerder is
- Beperkte functionaliteit: omdat Minimal API’s zijn ontworpen om lightweight te zijn, hebben ze mogelijk niet alle functies en mogelijkheden die gewenst zijn voor een project.
- Leercurve: Minimal API’s vereisen een nieuwe manier van denken en programmeren, wat kan leiden tot een steile leercurve.
- Gebrek aan documentatie: aangezien Minimal API’s nog relatief nieuw zijn, kan het zijn dat er nog niet veel documentatie en informatie beschikbaar is over het gebruik ervan.
- Mogelijkheid van toekomstige veranderingen: omdat Minimal API’s nog in ontwikkeling zijn, is er de mogelijkheid dat er in de toekomst veranderingen worden aangebracht in de manier waarop ze werken of dat ze niet meer worden ondersteund, wat kan leiden tot problemen met toekomstige updates of onderhoud.
Hoewel minimal API’s een aantrekkelijke optie kunnen zijn voor sommige ontwikkelaars, is het belangrijk om deze mogelijke uitdagingen en beperkingen in overweging te nemen voordat je besluit om ze te gebruiken voor jouw project.
Overige features van Minimal API’s
Omdat Minimal API’s de meest belangrijkste features van ASP.NET Core implementeert (zoals o.a. model binding, authenticatie en autorisatie, dependency injection, parameter binding (beschikbaar vanaf .NET 7)) zijn ze zeker ook geschikt voor productie omgevingen.
Model binding
C# Minimal API’s ondersteunen het gebruik van model binding. Model binding biedt de mogelijkheid om HTTP request data op C# objecten te mappen. Dit maakt het eenvoudiger om te werken met complexe data objecten en vergt nog minder boiler-plate code.
Dependency Injection
Een van de meest gebruikte patterns is Depedency Injection (DI). In Minimal API’s is het vrij eenvoudig om DI toe te passen. In onderstaand voorbeeld wordt “todoService” geïnjecteerd.
Voordeel van het gebruik van Depedency Injection is dat de overzicht van de Minimal API’s in de program.cs class wordt behouden terwijl de logica in daarvoor specifieke classes wordt geplaatst.
Parameter binding
Parameter binding houdt in dat inkomende HTTP-requests worden gekoppeld aan method parameters. Hierdoor kunnen deze requests op een gestructureerde en efficiënte manier worden verwerkt. Minimal API’s in ASP.NET Core 7 bieden verschillende typen parameter binding, waaronder FromQuery, FromRoute, FromHeader en FromBody.
Conclusie
Minimal APIs kan gezien worden als een alternatief voor het bouwen van je HTTP API, het is zeker niet bedoeld om ASP.NET Core MVC te vervangen. Minimal API’s bieden een eenvoudige en efficiënte manier om web applicaties en API’s te ontwikkelen. Dit alles met minimale overhead, minimal gebruik van boiler-plate code met als resultaat high performance applicaties die in staat zijn grote aantallen HTTP requests in korte tijd af te handelen. Minimal API’s zijn met name geschikt voor gebruik in projecten waarbij een gering aantal API endpoints gebruikt wordt. Al met al zeker het overwegen waard in combinatie met de overstap naar .NET6 en hoger.
Over de auteur
Pieter Baart
Lead developer Bergler Software Solutions
