AsyncAPI x MuleSoft. Wat is het? Wat zijn de voordelen? En hoe werkt het? In deze blogpost duiken we in de wereld van AsyncAPI met MuleSoft, aan de hand van een concreet voorbeeld.
Wat is AsyncAPI?
AsyncAPI is een open-source specificatie die asynchrone API’s en Event-Driven Architecture beschrijft. Het is geïnspireerd door de bekende OpenAPI Specification en lijkt qua structuur en gebruiksgemak daarop, maar terwijl OpenAPI zich richt op synchrone (request-response) communicatie, is AsyncAPI ontworpen voor systemen waar communicatie asynchroon plaatsvindt. Meer informatie en de documentatie zijn hier te vinden.
AsyncAPI ondersteuning in MuleSoft
AsyncAPI integratie met MuleSoft biedt vele voordelen voor het bouwen van event-driven architecturen.
Het brengt een duidelijke en gestandaardiseerde manier om asynchrone API’s te documenteren en ontwerpen. Met AsyncAPI in MuleSoft kunnen ontwikkelaars ervoor zorgen dat hun API’s consistente structuren volgen door herbruikbare componenten te definiëren, zoals schema’s en berichten, met functionaliteiten vergelijkbaar met die welke al beschikbaar zijn voor RAML en OAS.
AsyncAPI specificaties kunnen worden ontworpen in Anypoint Design Center met behulp van vertrouwde tools. Deze specificaties kunnen worden gevalideerd via Anypoint API Governance, waardoor wordt gegarandeerd dat ze voldoen aan bedrijfsstandaarden en best practices. Zodra ze klaar zijn, kunnen ze worden gepubliceerd naar Anypoint Exchange, waardoor ze gemakkelijk te delen en hergebruiken zijn tussen teams. Consumenten kunnen deze specificaties ook bekijken via Anypoint API Community Manager en Experience Hub, wat hun toegankelijkheid verbetert.
AsyncAPI integratie maakt implementatie ook eenvoudiger. Ontwikkelaars kunnen flows direct vanuit de specificatie scaffolden in Anypoint Studio of Code Builder. Dit genereert automatisch flows en configureert connectors vooraf, wat tijd bespaart en ervoor zorgt dat het project goed gestructureerd is. Deze functionaliteit is echter momenteel alleen beschikbaar in open beta ondersteuning, die moet worden ingeschakeld door de Anypoint Platform Organisation Admin en de vereiste minimum Mule runtime is 4.6. Vanaf vandaag zijn message brokers die worden ondersteund door APIKit voor AsyncAPI Kafka, Anypoint MQ, Salesforce platform events en Solace PubSub+.
Een AsyncAPI x MuleSoft voorbeeld
Een AsyncAPI specificatie ontwerpen
Laten we beginnen met een eenvoudig voorbeeld van een asynchrone API, waarvan het doel is het afhandelen van het aanmaken, bijwerken en verwijderen van gebruikersaccounts.
De eerste regel, asyncapi declareert de versie van de specificatie. Vanaf nu ondersteunt Anypoint Platform versies 2.0 en 2.6, terwijl de nieuwste voor AsyncAPI 3.0 is. Vervolgens hebben we een defaultContentType – is niet vereist, maar kan worden toegevoegd als een goede praktijk om het media-type in de specificatie te definiëren.
In het servers veld definiëren we verbindingsinformatie over de message brokers, zoals protocol, host, poort, beveiliging en pathname. In dit voorbeeld gebruiken we Kafka als message broker.
Het veld channels vertegenwoordigt de communicatiepaden of topics waardoor berichten worden gepubliceerd of waarop wordt geabonneerd, met velden zoals address, message en operations. Het lijkt op resources en methods maar dan voor RESTful API’s.
Het components veld bevat herbruikbare definities voor berichten, schema’s, beveiligingsschema’s en andere objecten waarnaar mogelijk wordt verwezen in de specificatie. Deze componenten kunnen vervolgens meerdere keren worden gerefereerd in verschillende secties van de specificatie.
Publiceren naar exchange
Na het ontwerpen van een AsyncAPI specificatie kunnen we deze als asset publiceren naar Exchange, op dezelfde manier als we doen met RAML en OAS. De gepubliceerde asset ziet er dan zo uit:
De flows scaffolden in studio
Zodra de Beta versie is ingeschakeld, kunnen we de flows binnen het project scaffolden. Dit proces is vergelijkbaar met het werken met elke andere specificatie: we voegen simpelweg de AsyncAPI specificatie toe als module aan het project. Dit genereert twee belangrijke configuratiebestanden: het global bestand en het hoofdbestand, dat de automatisch gegenereerde flows bevat. Deze flows bevatten message listener componenten met servers en channels toegevoegd volgens de specificatie. De publishing operatie moet handmatig worden toegevoegd terwijl we doorgaan met het implementeren van de event-driven logica.
In het global bestand krijgen we naast de APIKit voor AsyncAPI ook vooraf geconfigureerde message broker connectors, in dit geval Kafka producer en Kafka listener.
Scaffolding voegt ook een dev-properties bestand toe aan het project, dat we kunnen vinden in het src/main/resources pad, waarin we verder onze omgevingsspecifieke sleutelwaarden kunnen toevoegen.
Kort samengevat
Over het algemeen volgt het gegenereerde project best practices wat betreft structuur en naamgevingsconventies, wat handig is als we geen templates gebruiken voor ons project. De APIKit’s Message Listener component is een nuttige toevoeging maar blijft vrij basic, omdat instellingen zoals Ack mode of Poll timeout nog niet kunnen worden geconfigureerd. Echter, AsyncAPI’s integratie met MuleSoft biedt
