REL03-BP03 Bereitstellen von Serviceverträgen pro API
Serviceverträge sind dokumentierte Vereinbarungen zwischen API-Herstellern und Verbrauchern, die in einer maschinenlesbaren API-Definition festgehalten sind. Eine Vertragsversionsverwaltungsstrategie ermöglicht es Verbrauchern, die vorhandene API weiter zu verwenden und ihre Anwendungen auf eine neuere API zu migrieren, wenn sie bereit sind. Die Bereitstellung durch den Produzenten kann jederzeit erfolgen, solange der Vertrag eingehalten wird. Die Serviceteams können den Technologie-Stack ihrer Wahl verwenden, um den API-Vertrag zu erfüllen.
Gewünschtes Ergebnis:
Typische Anti-Muster: Anwendungen, die mit serviceorientierten Architekturen oder Microservice-Architekturen erstellt wurden, können unabhängig voneinander arbeiten und verfügen gleichzeitig über eine integrierte Laufzeitabhängigkeit. Änderungen, die für einen API-Verbraucher oder -Hersteller bereitgestellt werden, beeinträchtigen die Stabilität des Gesamtsystems nicht, wenn beide Seiten einen gemeinsamen API-Vertrag einhalten. Komponenten, die über Service-APIs kommunizieren, können unabhängige funktionale Releases, Upgrades von Laufzeitabhängigkeiten oder ein Failover auf eine Notfallwiederherstellung (DR) ausführen, ohne dass sich dies gegenseitig beeinträchtigt. Darüber hinaus können spezialisierte Services unabhängig voneinander skaliert werden und können dabei den Ressourcenbedarf absorbieren, ohne dass andere Services ebenfalls skaliert werden müssen.
-
Erstellung von Service-APIs ohne stark typisierte Schemata. Dies führt zu APIs, die nicht zum Generieren von API-Bindungen und Payloads verwendet werden können, die nicht programmgesteuert validiert werden können.
-
Keine Versionsverwaltungsstrategie, weshalb API-Verbraucher dazu gezwungen sind, Updates zu installieren, Releases einzuspielen oder eine Notfallwiederherstellung durchzuführen, wenn sich Serviceverträge weiterentwickeln.
-
Fehlermeldungen, die Details der zugrundeliegenden Service-Implementierung preisgeben, anstatt Integrationsfehler im Kontext und in der Sprache der Domain zu beschreiben.
-
Keine Verwendung von API-Verträgen zur Entwicklung von Testfällen und zur Simulation von API-Implementierungen, um unabhängige Tests von Servicekomponenten zu ermöglichen.
Vorteile der Nutzung dieser bewährten Methode: Verteilte Systeme, die aus Komponenten bestehen, die über API-Serviceverträge kommunizieren, können die Zuverlässigkeit verbessern. Entwickler können potenzielle Probleme schon früh im Entwicklungsprozess erkennen, indem sie während der Kompilierung eine Typprüfung durchführen, um sicherzustellen, dass Anfragen und Antworten dem API-Vertrag entsprechen und die erforderlichen Felder vorhanden sind. API-Verträge bieten eine übersichtliche, selbstdokumentierende Schnittstelle für APIs und sorgen für eine bessere Interoperabilität zwischen verschiedenen Systemen und Programmiersprachen.
Risikostufe, wenn diese bewährte Methode nicht eingeführt wird: Mittel
Implementierungsleitfaden
Sobald Sie Geschäftsbereiche identifiziert und Ihre Workload-Segmentierung festgelegt haben, können Sie Ihre Service-APIs entwickeln. Definieren Sie zunächst maschinenlesbare Serviceverträge für APIs und implementieren Sie dann eine Strategie zur API-Versionsverwaltung. Wenn Sie bereit sind, Services über gängige Protokolle wie REST, GraphQL oder asynchrone Ereignisse zu implementieren, können Sie AWS-Services in Ihre Architektur einbinden, um Ihre Komponenten mit stark typisierten API-Verträgen zu integrieren.
AWS-Services für API-Serviceverträge
Implementieren Sie AWS-Services wie Amazon API Gateway
Implementierungsschritte
-
Definieren Sie zunächst einen Vertrag für Ihre API. In einem Vertrag werden die Funktionen einer API festgehalten und stark typisierte Datenobjekte und Felder für die API-Eingabe und -Ausgabe definiert.
-
Wenn Sie APIs in API Gateway konfigurieren, können Sie OpenAPI-Spezifikationen für Ihre Endpunkte importieren und exportieren.
-
Der Import einer OpenAPI-Definition vereinfacht die Erstellung Ihrer API und kann in AWS-Infrastructure as Code-Tools wie AWS Serverless Application Model
und AWS Cloud Development Kit (AWS CDK) integriert werden. -
Der Export einer API-Definition vereinfacht die Integration in API-Testtools und bietet Servicekunden eine Integrationsspezifikation.
-
-
Definieren und verwalten Sie GraphQL-APIs mit AWS AppSync, indem Sie eine GraphQL-Schema-Datei definieren, um Ihre Vertragsschnittstelle zu generieren und die Interaktion mit komplexen REST-Modellen, mehreren Datenbanktabellen oder Legacy-Services zu vereinfachen.
-
AWS Amplify
-Projekte, die in AWS AppSync integriert sind, generieren stark typisierte JavaScript-Abfragedateien, die Sie sowohl in Ihrer Anwendung als auch in einer AWS AppSync-GraphQL-Client-Bibliothek für Amazon DynamoDB -Tabellen verwenden können. -
Wenn Sie Serviceereignisse aus Amazon EventBridge verarbeiten, befolgen diese Ereignisse Schemata, die bereits in der Schemaregistrierung existieren oder die Sie mit der OpenAPI-Spezifikation definieren. Mit einem in der Registrierung definierten Schema können Sie auch Client-Bindungen aus dem Schemavertrag generieren, um Ihren Code in Ereignisse zu integrieren.
-
API erweitern oder versionieren Die Erweiterung einer API ist eine einfachere Option, wenn Felder hinzugefügt werden, die mit optionalen Feldern oder Standardwerten für Pflichtfelder konfiguriert werden können.
-
JSON-basierte Verträge für Protokolle wie REST und GraphQL können sich gut für eine Vertragserweiterung eignen.
-
XML-basierte Verträge für Protokolle wie SOAP sollten mit Service-Verbrauchern getestet werden, um festzustellen, ob eine Vertragserweiterung durchführbar ist.
-
-
Erwägen Sie bei der Versionsverwaltung einer API die Implementierung einer Proxy-Versionsverwaltung, bei der eine Fassade zur Unterstützung von Versionen verwendet wird, sodass die Logik in einer einzigen Codebasis verwaltet werden kann.
-
Mit API Gateway können Sie Anfrage- und von Antwortzuordnungen nutzen, um Vertragsänderungen einfacher zu übernehmen. Hierzu wird eine Fassade eingerichtet, die Standardwerte für neue Felder bereitstellt oder entfernte Felder aus einer Anfrage oder Antwort herausnimmt. Mit diesem Ansatz kann der zugrunde liegende Service mit einer einzelnen Codebasis betrieben werden.
-
Ressourcen
Zugehörige bewährte Methoden:
Zugehörige Dokumente:
Zugehörige Beispiele:
Zugehörige Videos:
Zugehörige Tools:
