Minimal APIs
Inleiding
Microsoft heeft in november 2021 .Net 6 met C# 10 uitgebracht. In C# 10 kunnen zogenaamde Minimal APIs gebouwd worden, maar waarin verschillen die van de Web API Server Controllers ?
Van Minimal APIs wordt ook gezegd dat ze beter geschikt zijn voor het doen bouwen van Micro Services. Wat zijn Micro Services dan en wat heeft de “cloud” ermee te maken? We gaan in deze post nader in op deze onderwerpen. De voorbeeldcode kun je hier en hier in Github terugvinden.
Micro Services
Een “monolitische” (monolithic) architectuur was in het verleden gangbaar voor veel software applicaties. Een grote centrale computer is vaak de hoofdrolspeler in een monolitische architectuur. Bij zo’n architectuur staat de computer bij het bedrijf dat de applicatie faciliteert (een on premise lokatie). Nadeel van zo’n constructie is dat het hele systeem off-line moet gaan als er wat aan de hand mocht zijn met een component in dat systeem (kapot gegane te vervangen hardware of software en/of het gewone reguliere onderhoud).
Men zag al snel de nadelen van een monolitische architectuur en men kwam tot de SOA architectuur (SOA =Service-Oriented Architecture). Bij een SOA architectuur is een applicatie opgesplitst in meerdere onafhankelijke onderdelen (Distributed Applications). De afzonderlijke onafhankelijke onderdelen communiceren met elkaar via een gemeenschappelijke “Enterprise Service Bus” (meestal via het internet). Dit alles om de continuïteit beter te doen waarborgen en om het onderhoud eenvoudiger te maken.
Voor de implementatie van deze architectuur werd gebruik werd gemaakt van technologieën zoals Web Services en WCF met berichten in XML-formaat (eXtensible Markup Language). Meer over Web Services in deze post over Serialisatie en deserialisatie.
Micro Services kunnen gezien worden als een architectuur dat verder uit de Service-Oriented Architecture is geëvolueerd. De applicatie wordt daarbij nog verder opgesplitst. De opgesplitste componenten (micro services) zijn autonoom en ze hebben event-driven “voelsprieten” naar events van andere componenten waardoor ze wat proactiever worden. De component komt in actie zodra ze merkt dat vanuit een andere component een event is uitgegaan.
Een Micro Service is niet bedoeld als een complete applicatie maar als een autonoom proactief radertje in een groot geheel waarbij dat ene radertje gericht is op een eigen specifieke taak.
Cloud Computing platforms
Een andere trend dat met de Micro Services gepaard gaat, is het doen onderbrengen in de “cloud” van van alles en nog wat. Een Cloud Service Provider (CSP) biedt daarbij allerlei diensten aan via haar Cloud Computing platform en jij kan als klant gebruik maken van die diensten. Bekende Cloud Service Providers zijn Google, Amazon en Microsoft met haar Azure cloud computing platform.
Bij een Cloud Computing platform bevindt alles zich in een data center van de Cloud Service Provider. Als klant heb jij via het internet toegang tot de diensten van de Cloud Service Provider (het staat in de “cloud”).
Een voorbeeld is het (tijdelijk) doen huren van een extra virtuele machine bij een Cloud Service Provider in plaats van het aanschaffen van een nieuwe server voor je eigen on premise serverpark.
Ook het onderbrengen van je Micro Service bij een cloud computing platform is een mogelijkheid. Een voordeel is dat extra (al dan niet tijdelijke) computer capaciteit ingehuurd kan worden (Operational Expenditure) voor je Micro Service.
Dit kan bijvoorbeeld nodig zijn om piekmomenten op te vangen. Extra computercapaciteit kan dan tijdelijk nodig zijn omdat je Micro Service het anders niet gaat trekken tijdens zo’n piekmoment. Zo heeft Microsoft in haar Azure cloud diensten de optie om het op- en afschalen van computer capaciteit automatisch te laten doen gaan als piekmomenten optreden.
Het opvangen van piekmomenten is wat lastiger/prijziger bij een monolitische architectuur. Je moet extra capaciteit inkopen waarbij je permanent vast zit aan die extra capaciteit (Capital Expenditure) en het extra ingekochte wordt mogelijk alleen maar benut tijdens die piekmomenten (gedurende die twee dagen per maand dat de piekmomenten optreden?).
Minimal API
Maar wat heeft een Minimal API te maken met Micro Services in de cloud? Het antwoord is dat een Micro Service gebruik kan maken van Minimal APIs of van Web API Server Controllers voor het doen uitvoeren van haar taak.
De Micro Service kan voor haar taak al genoeg hebben aan een aantal Minimal APIs / Web API Server Controllers waardoor de Micro Service niet meer is dan dat, maar dat hoeft niet altijd zo te zijn. Daar komt de verwarring dan ook vandaan. Een Micro Service is geen Minimal API en/of een Web API Server Controller, maar kan uit meer bestaan.
De gedachte is dat een Minimal API mogelijk meer geschikt zou zijn voor het doen optuigen van de Micro Service dat in de cloud draait. Dit omdat een Web API Server Controller voor een Micro Service in de cloud te veel “overhead” zou bevatten t.o.v. een Minimal API en dan ook “te zwaar” zou zijn voor de Micro Service.
Maar of dat zo is, dat is voor discussie vatbaar en het zal ongetwijfeld ook afhangen van wat de Micro Service precies moet doen.
ASP .NET Core Web API
We maken een ASP .NET Core Web API om het één en ander toe te lichten. Daarbij maken we gebruik van de Visual Studio 2022 IDE waarbij we voor de voorbeeld solution .Net 6 gebruiken met C# 10. We creëren een nieuw project en we kiezen de ASP .NET Core Web API-project template:
In Visual Studio verschijnt vervolgens een “Configure your new project“-dialoogscherm waarin we de naam van de solution opgeven en de folder waarin het één en ander moet komen. We krijgen na dat dialoogscherm een “Additional information“-dialoogscherm:
We maken een .NET 6.0 (Long-term support)-solution waarin we de “Use controllers (uncheck to use minimal APIs)“-checkbox aanvinken voor het doen bouwen van een “traditionele” Web API Server Controller. De broncode van de Web API Server Controller-solution kun je hier terugvinden.
Verder maken we een solution voor het doen maken van een minimal API waarbij we de “Use controllers (uncheck to use minimal APIs)“-checkbox uitvinken. De broncode van de minimal API-solution kun je hier terugvinden.
De solutions doen uiteindelijk precies hetzelfde. Ze voeren CRUD-operaties uit op een tabel in een SQL Server database. In dit voorbeeld een tabel met de naam “EIGENAAR” dat zich bevindt in SQL Server database “VOORBEELD”.
We vinken voor allebei de solutions de “Enable OpenAPI support“-checkbox aan zodat we gebruik kunnen maken van Swagger voor het doen testen van de ASP .NET Core Web API.
Onze twee solutions gaan er in de Visual Studio Solution Explorer als bovenstaand uitzien. In de “traditionele” Web API Server Controller-solution vinden we een aparte Controllers-folder met daarin class module-bestanden voor onze controller action methods. In de minimal API-solution stoppen we de minimal APIs in bestand Program.cs.
We gaan de HaalopEigenaren minimal API nader bekijken (de volledige code kun je terugvinden op Github):
app.MapGet("/HaalOpEigenaren",
async (DbContextClass dbContextClass) =>
{
try
{
return Results.Ok(await dbContextClass
.EIGENAAR
.ToListAsync());
}
catch (Exception ex)
{
return Results.Problem(
"Er is iets fout gegaan met
minimal API HaalOpEigenaren - " +
ex.Message);
}
});
Wat we over deze nieuwe manier van Web APIs bouwen (minimal APIs) kunnen zeggen:
- We kunnen alles desgewenst in één bestand zetten.
Dat was ook een opmerking van de developer community dat voor C# wel erg veel bestanden nodig zijn voor het doen bouwen van een Web API. Dat is niet tegen dovemansoren gezegd want Microsoft heeft het bij de minimal APIs mogelijk gemaakt dat alles in één bestand gezet kan worden.
Eén bestand is leuk als de minimal API klein en bescheiden blijft, maar blijft één bestand leuk als de minimal api gaat groeien qua functionaliteit en complexiteit?
We hebben in dit voorbeeld de klassendefinities (Eigenaar.cs, Fout.cs en WeatherForecast.cs) in aparte bestanden gezet, maar we hadden die ook in de Program.cs kunnen zetten. - Er wordt gebruik gemaakt van anonieme functies en lambda expressies.
Prettig voor de ontwikkelaars die bekend zijn met Node.js en Express.js. - Minder “ceremony”
minder geneste accolades (mede door de in C# 9 geïntroduceerde top level calls). - Minimalisme,
met een verb (GET, PUT, POST en DELETE) geef je aan wat de aard van het verzoek is naar een gegevensbron en die hebben we bij de minimal APIs ook middels een .MapGet, een .MapPost, een .MapPut, en een .MapDelete. Verder wordt voor de end point een route pattern meegegeven als eerste parameter (we krijgen in dit voorbeeld deze url: http://localhost:1234/HaalOpEigenaren). - HTTP Status Codes hebben we ook nog steeds bij minimal APIs. We gebruiken daarvoor de Results static class. In dit voorbeeld gebruiken we de Results.Ok welke buiten het gewenste resultaat een HTTP Status Code 200 geeft en een Results.Problem welke een HTTP Status Code 500 geeft indien dingen niet gaan zoals gewenst.
Slot
Microsoft heeft met de minimal API in C# 10 een nieuwe manier van Web APIs bouwen geïntroduceerd.
Minimal APIs worden met Micro Services in één adem genoemd waardoor de indruk wordt gewekt dat een Micro Service een minimal API is. Dat hoeft echter niet zo te zijn en in deze post zijn we dan ook nader ingegaan op wat een Micro Service is.
Micro Services en de Cloud worden ook in één vleug genoemd en we hebben in deze post ook aandacht besteed aan wat een Cloud Computing platform is en hoe een Micro Service tot haar recht komt als ze wordt ondergebracht bij zo’n platform.
We hebben ten slotte met de Visual Studio 2022 IDE een minimal API gebouwd en de code nader bekeken. Geconcludeerd kan worden dat minimal APIs zich goed lenen voor het maken van lichtgewicht Web APIs. Minimal APIs zijn ook goed voor het snel in elkaar zetten van een mock up. En dat alles zonder al te veel overhead en “ceremony”.
Veel ontwikkelaars zullen, als het allemaal wat serieuzer gaat worden, toch weer terugkeren naar de “traditionele” Web API Server Controllers. Ook omdat de minimal API nog een beperkte subset is van de Web API Server Controllers. Maar dat zal in de toekomst ongetwijfeld veranderen als Microsoft nieuwe features toevoegt aan haar minimal APIs waardoor de minimal API niet alleen “light weight” blijft, maar ook beter kan voldoen aan de iets geavanceerdere behoeftes.
Hopelijk ben je met deze posting weer wat wijzer geworden en ik hoop je weer terug te zien in één van mijn volgende blog posts. Wil je weten wat ik nog meer over C# heb geschreven? Hit the C# button…