Erstellen, Weiterentwickeln und Verwalten von Versionen von Microservice-APIs und -verträgen
Tipp
Diese Inhalte sind ein Auszug aus dem eBook „.NET Microservices Architecture for Containerized .NET Applications“, verfügbar unter .NET Docs oder als kostenlos herunterladbare PDF-Datei, die offline gelesen werden kann.
Eine Microservice-API stellt einen Vertrag zwischen dem Dienst und dessen Clients dar. Sie können einen Microservice nur dann unabhängig weiterentwickeln, wenn Sie den zugehörigen API-Vertrag nicht brechen. Aus diesem Grund ist dieser Vertrag so wichtig. Wenn Sie den Vertrag ändern, wirkt sich dies auf Ihre Clientanwendungen oder Ihr API-Gateway aus.
Die Art der API-Definition richtet sich nach dem von Ihnen verwendeten Protokoll. Wenn Sie z. B. Messaging (wie AMQP) verwenden, besteht die API aus den Nachrichtentypen. Wenn Sie HTTP- und RESTful-Dienste verwenden, besteht die API aus den URLs sowie den JSON-Formaten für Anforderungen und Antworten.
Auch wenn Sie den ersten Vertrag gut durchdacht haben, wird sich die Dienst-API im Laufe der Zeit ändern. Wenn das geschieht, können Sie in der Regel nicht alle Clients dazu zwingen, ein Upgrade auf Ihren neuen API-Vertrag durchzuführen. Dies gilt besonders dann, wenn es sich bei Ihrer API um eine öffentliche API handelt, die von mehreren Clientanwendungen verwendet wird. In der Regel müssen Sie neue Versionen eines Diensts inkrementell auf eine Weise bereitstellen, sodass sowohl die alte als auch die neue Version eines Dienstvertrags gleichzeitig ausgeführt werden. Deshalb ist es wichtig, dass eine Strategie für die Versionsverwaltung Ihres Diensts vorhanden ist.
Wenn die Änderungen an der API klein sind, wenn Sie also Ihrer API zum Beispiel Attribute oder Parameter hinzufügen, sollten Clients, die eine ältere API verwenden, umschalten und mit der neueren Version des Diensts arbeiten. Möglicherweise können Sie Standardwerte für fehlende Attribute bereitstellen, die erforderlich sind, und die Clients können überflüssige Antwortattribute ignorieren.
Allerdings müssen Sie manchmal größere Änderungen an einer Dienst-API vornehmen und verstoßen dadurch gegen die Kompatibilitätsanforderungen. Da Sie möglicherweise nicht dazu in der Lage sind, Clientanwendungen oder Dienste zu einem sofortigen Upgrade auf die neue Version zu zwingen, muss ein Dienst ältere Versionen der API für einen gewissen Zeitraum unterstützen. Wenn Sie einen HTTP-basierten Mechanismus wie REST verwenden, können Sie z.B. die Versionsnummer der API in die URL oder in einen HTTP-Header einbetten. Dann können Sie sich entscheiden, ob Sie beide Versionen des Diensts gleichzeitig in die gleiche Dienstinstanz implementieren, oder ob Sie verschiedene Instanzen bereitstellen, die jeweils eine Version der API verarbeiten. Ein guter Ansatz für diese Funktionalität ist das Vermittlermuster (z. B. die MediatR-Bibliothek) zum Entkoppeln der verschiedenen Implementierungsversionen in unabhängige Handler.
Und wenn Sie eine REST-Architektur verwenden, ist Hypermedia die beste Lösung für die Versionsverwaltung Ihrer Dienste und das Zulassen von APIs, die sich weiterentwickeln lassen.
Zusätzliche Ressourcen
Scott Hanselman. ASP.NET Core RESTful Web API versioning made easy (Versionsverwaltung von RESTful-Web-APIs in ASP.NET Core leicht gemacht)
https://www.hanselman.com/blog/ASPNETCoreRESTfulWebAPIVersioningMadeEasy.aspxVersionsverwaltung einer RESTful-Web-API
https://learn.microsoft.com/azure/architecture/best-practices/api-design#versioning-a-restful-web-apiRoy Fielding. Versioning, Hypermedia, and REST (Versionsverwaltung, Hypermedia und REST)
https://www.infoq.com/articles/roy-fielding-on-versioning