DRY January #3
- thim90
- Jan 29
- 3 min read
Custom API
Dry January gaat niet alleen over stoppen, maar misschien nog wel meer over volhouden.
En daarmee zijn we aangekomen bij de derde en laatste blog van mijn Dry January-reeks.
In de vorige blogs ging het vooral over de client.
Eerst door logica expliciet te maken, daarna door UI consistent te houden.
Maar dat blijft allemaal aan de buitenkant van het platform.
En als we DRY écht serieus nemen, dan wil je dat belangrijke logica op één plek wordt onderhouden.
Alleen de client is daarvoor vaak niet voldoende.
In deze blog gaan we daarom een laag dieper.
Richting een van mijn favoriete onderdelen binnen het Power Platform: Dataverse Custom APIs.
Wanneer DRY client-side niet meer genoeg is
Zolang logica bedoeld is om:
de gebruiker te begeleiden
feedback te geven
de ervaring voorspelbaar te maken
dan is client-side een prima plek.
Maar zodra een regel:
altijd moet gelden
onafhankelijk is van het kanaal
data mag blokkeren of corrigeren
Dan hoort die regel niet meer in de client. Op dat moment moet het platform het overnemen.
En daar komen Custom APIs en plugins in beeld.
Eerst even scherp: Actions, Custom APIs en plugins
Deze begrippen worden vaak door elkaar gebruikt. Dat is logisch, want ze raken elkaar.
Maar hun rol is verschillend.
Actions zijn de klassieke manier om gedrag te modelleren in Dataverse.
Ze bestaan al sinds de XRM-tijd en werden vaak gebruikt in combinatie met workflows of plugins.
Een Action:
wordt expliciet aangeroepen
heeft input- en outputparameters
kent geen automatische trigger zoals een CRUD-event
De implementatie van een Action gebeurt meestal via:
een plugin die aan de Action is gekoppeld
of via geconfigureerde stappen, vergelijkbaar met classic workflows
Een belangrijk verschil met classic workflows is dat Actions transactiebewust kunnen zijn.
Dat betekent dat je kunt instellen dat de volledige operatie wordt teruggedraaid bij een fout.
Custom APIs zijn de moderne opvolger van dit Action concept.
Wat is een Custom API eigenlijk?
Een Custom API is een expliciete operatie in Dataverse.
Geen tabel. Geen event. Maar een gedefinieerde actie met een contract.
Net als bij Actions definieer je:
inputparameters
outputparameters
Tip 💡: zelf gebruik ik vaak de Custom API Manager in de XrmToolbox voor het aanmaken en wijzigen van Custom API's
Maar anders dan bij Actions configureer je geen stappen in de API zelf
Een Custom API beschrijft wat er gebeurt, niet hoe het wordt uitgevoerd.
Een Custom API:
wordt expliciet aangeroepen
kan synchroon of asynchroon draaien
respecteert Dataverse-security
is aanroepbaar vanuit o.a.:
Canvas Apps
Custom Pages
Model-Driven Apps (JavaScript)
Power Automate
externe integraties
Kort gezegd: één actie, meerdere consumers.
Hoe de logica wordt uitgevoerd, hangt af van hoe je de Custom API implementeert.
Functions in Microsoft Dataverse (preview)
Sinds kort biedt Microsoft Dataverse Functions aan (preview).
Dit zijn low-code implementaties van Custom APIs.
Technisch gezien:
definieer je een Custom API
koppel je daar Power Fx-logica aan
en wordt die logica uitgevoerd wanneer de Custom API wordt aangeroepen
Je kunt dit zien als low-code plugins.
Voor relatief eenvoudige validaties of bewerkingen kan dit een interessant alternatief zijn voor C#-plugins.
Maar belangrijk om te benoemen: low-code betekent niet automatisch beter.
Voor complexere logica, performance kritische processen of transacties die niet mogen falen, blijft een klassieke plugin vaak de beste keuze.
Custom APIs betekenen dus niet automatisch custom code.
Sterker nog, soms betekenen ze vooral: expliciet maken wat er gebeurt.
Custom APIs als orkestratiepunt
Een Custom API kan ook puur dienen als signaal.
Power Automate kent namelijk de trigger: When an action is performed.
Deze trigger gaat af nadat de Custom API is uitgevoerd. Eventuele logica die direct aan de API is gekoppeld,wordt dus eerst afgehandeld.
Daarna kan Power Automate:
dezelfde inputparameters ontvangen
outputparameters verwerken
aanvullende stappen uitvoeren
In dit model gebruik je de Custom API als orkestratiepunt.
Niet om alles zelf te doen,maar om gedrag expliciet te maken.
Custom APIs en plugins (pro-code)
Zodra gedrag:
complex wordt
performance kritisch is
onderdeel is van een transactie
niet mag falen
kom je vrijwel altijd uit bij plugins.
Een plugin draait server-side, is transactiebewust en werkt kanaal onafhankelijk.
Dat maakt plugins de juiste plek voor:
afdwingen van businessregels
waarborgen van data-integriteit
consistente platformlogica
In de praktijk zie je vaak dit patroon:
De Custom API definieert wat er gebeurt. De plugin implementeert hoe dat gebeurt.
De API fungeert als contract. De plugin als uitvoering.
Dat maakt verantwoordelijkheden expliciet en voorkomt dat logica “verstopt” raakt in losse plugins of flows.
DRY stopt niet bij de UI. En zeker niet bij de client.
Wie DRY serieus neemt, zal uiteindelijk bij Custom APIs en plugins uitkomen.
Zeker logica die op meerdere plekken binnen een applicatie of proces noodzakelijk is.
Comments