Microservice-API's en contracten voor microservice maken, ontwikkelen en versiebeheer
Tip
Deze inhoud is een fragment uit het eBook, .NET Microservices Architecture for Containerized .NET Applications, beschikbaar op .NET Docs of als een gratis downloadbare PDF die offline kan worden gelezen.
Een microservice-API is een contract tussen de service en de bijbehorende clients. U kunt een microservice alleen onafhankelijk ontwikkelen als u het API-contract niet onderbreekt. Daarom is het contract zo belangrijk. Als u het contract wijzigt, heeft dit invloed op uw clienttoepassingen of uw API-gateway.
De aard van de API-definitie is afhankelijk van het protocol dat u gebruikt. Als u bijvoorbeeld berichten gebruikt, zoals AMQP, bestaat de API uit de berichttypen. Als u HTTP- en RESTful-services gebruikt, bestaat de API uit de URL's en de JSON-indelingen voor aanvragen en antwoorden.
Zelfs als u goed nadenkeert over uw eerste contract, moet een service-API na verloop van tijd veranderen. Wanneer dat gebeurt, en vooral als uw API een openbare API is die door meerdere clienttoepassingen wordt gebruikt, kunt u doorgaans niet afdwingen dat alle clients een upgrade uitvoeren naar uw nieuwe API-contract. Normaal gesproken moet u nieuwe versies van een service incrementeel implementeren op een manier waarop zowel oude als nieuwe versies van een servicecontract gelijktijdig worden uitgevoerd. Daarom is het belangrijk om een strategie te hebben voor uw serviceversiebeheer.
Wanneer de API-wijzigingen klein zijn, zoals als u kenmerken of parameters toevoegt aan uw API, moeten clients die een oudere API gebruiken, overschakelen en werken met de nieuwe versie van de service. Mogelijk kunt u standaardwaarden opgeven voor ontbrekende kenmerken die vereist zijn en kunnen de clients mogelijk eventuele extra antwoordkenmerken negeren.
Soms moet u echter belangrijke en incompatibele wijzigingen aanbrengen in een service-API. Omdat u mogelijk niet kunt afdwingen dat clienttoepassingen of -services onmiddellijk worden bijgewerkt naar de nieuwe versie, moet een service oudere versies van de API gedurende een bepaalde periode ondersteunen. Als u een op HTTP gebaseerd mechanisme zoals REST gebruikt, is het insluiten van het API-versienummer in de URL of in een HTTP-header. Vervolgens kunt u kiezen tussen het gelijktijdig implementeren van beide versies van de service binnen hetzelfde service-exemplaar of het implementeren van verschillende exemplaren die elk een versie van de API verwerken. Een goede aanpak voor deze functionaliteit is het bemiddelaarpatroon (bijvoorbeeld mediatR-bibliotheek) om de verschillende implementatieversies los te koppelen aan onafhankelijke handlers.
Ten slotte is Hypermedia, als u een REST-architectuur gebruikt, de beste oplossing voor het versiebeheer van uw services en het toestaan van aanpasbare API's.
Aanvullende bronnen
Scott Hanselman. ASP.NET Core RESTful Web API-versiebeheer is eenvoudig gemaakt
https://www.hanselman.com/blog/ASPNETCoreRESTfulWebAPIVersioningMadeEasy.aspxVersiebeheer van een RESTful-web-API
https://learn.microsoft.com/azure/architecture/best-practices/api-design#versioning-a-restful-web-apiRoy Fielding. Versiebeheer, Hypermedia en REST
https://www.infoq.com/articles/roy-fielding-on-versioning