So machen Sie Ihre REST-APIs abwärtskompatibel

Representational State Transfer, allgemein als REST bekannt, ist ein Architekturstil - eine Reihe von Einschränkungen, die zum Implementieren zustandsloser Dienste verwendet werden, die unter HTTP ausgeführt werden. Eine RESTful-API entspricht den REST-Einschränkungen. Sie können RESTful-APIs mit vielen verschiedenen Programmiersprachen erstellen.

Die Aufrechterhaltung der Abwärtskompatibilität zwischen verschiedenen Versionen Ihrer API ist von größter Bedeutung, um sicherzustellen, dass Ihre API mit allen Clients kompatibel bleibt, die sie verwenden. In diesem Artikel wird erläutert, wie Sie die Abwärtskompatibilität in Ihren RESTful-APIs aufrechterhalten können.

Beispiel für eine API-Kompatibilität

Angenommen, Sie haben eine API in der Produktion, die von verschiedenen Clients verwendet wird. Wenn Sie der API nun weitere Funktionen hinzufügen möchten, sollten Sie sicherstellen, dass die Clients, die die alte API verwenden, entweder die neue oder die alte API verwenden können. Mit anderen Worten, Sie sollten sicherstellen, dass die vorhandene Funktionalität der API erhalten bleibt, während die neue Funktionalität hinzugefügt wird.

Eine API ist abwärtskompatibel, wenn ein Client (ein Programm, das zum Konsumieren der API geschrieben wurde), das mit einer Version der API arbeiten kann, mit zukünftigen Versionen der API genauso arbeiten kann. Mit anderen Worten, eine API ist zwischen Releases abwärtskompatibel, wenn die Clients nahtlos mit einer neuen Version der API arbeiten können sollen.

Lassen Sie uns dies anhand eines Beispiels verstehen. Angenommen, Sie haben eine API-Methode namens GetOrders, wie im folgenden Codeausschnitt gezeigt.

[HttpGet]

[Route ("GetOrders")]

 public IActionResult GetOrders (int customerId, int orderId = 0)

 {

   var result = _orderService.GetOrdersForCustomer (

                 customerId, orderId);

   return Ok (Ergebnis);

 }}

Die Aktionsmethode GetOrders akzeptiert eine Kunden-ID und eine Auftrags-ID als Parameter. Beachten Sie, dass der zweite Parameter, orderID, optional ist. Die private Methode GetOrdersForCustomer ist unten angegeben.

private Liste GetOrdersForCustomer (int customerId, int orderId)

{

   // Schreiben Sie hier Code, um einen oder mehrere Auftragsdatensätze zurückzugeben

}}

Die GetOrdersForCustomer-Methode gibt alle Bestellungen eines Kunden zurück, wenn die als Parameter an ihn übergebene orderId 0 ist. Wenn die orderId ungleich Null ist, gibt sie eine Bestellung zurück, die sich auf den Kunden bezieht, der durch die als Argument übergebene customerId identifiziert wurde.

Da der zweite Parameter der Aktionsmethode GetOrders optional ist, können Sie einfach die customerId übergeben. Wenn Sie nun den zweiten Parameter der Aktionsmethode GetOrders so ändern, dass er obligatorisch ist, können die alten Clients der API die API nicht mehr verwenden.  

[HttpGet]

[Route ("GetOrders")]

 public IActionResult GetOrders (int customerId, int orderId)

 {

   var result = _orderService.GetOrdersForCustomer

                 (customerId, orderId);

   return Ok (Ergebnis);

 }}

Und genau so können Sie die Kompatibilität Ihrer API beeinträchtigen! Im folgenden Abschnitt werden die Best Practices erläutert, die angewendet werden können, um Ihre API abwärtskompatibel zu machen.

API-Kompatibilitätstipps

Nachdem wir nun wissen, worum es bei dem Problem geht, wie gestalten wir unsere APIs auf die empfohlene Weise? Wie stellen wir sicher, dass unsere RESTful-API abwärtskompatibel ist? In diesem Abschnitt werden einige der Best Practices aufgeführt, die in dieser Hinsicht befolgt werden können. 

Stellen Sie sicher, dass die Komponententests bestanden wurden

Sie sollten Tests schreiben lassen, die überprüfen, ob die Funktionalität mit einer neuen Version der API intakt ist. Die Tests sollten so geschrieben werden, dass sie fehlschlagen, wenn Abwärtskompatibilitätsprobleme auftreten. Idealerweise sollten Sie über eine Testsuite für API-Tests verfügen, die fehlschlägt und Sie benachrichtigt, wenn Probleme mit der Abwärtskompatibilität der API auftreten. Sie können auch eine automatisierte Testsuite an die CI / CD-Pipeline anschließen, die die Abwärtskompatibilität überprüft und bei Verstößen benachrichtigt.

Ändern Sie niemals das Verhalten von HTTP-Antwortcodes

Sie sollten niemals das Verhalten von HTTP-Antwortcodes in Ihrer API ändern. Wenn Ihre API 500 zurückgibt, wenn keine Verbindung zur Datenbank hergestellt werden kann, sollten Sie sie nicht in 200 ändern. Wenn Sie HTTP 404 zurückgeben, wenn eine Ausnahme auftritt, und Ihre Clients dies und das Antwortobjekt verwenden, um zu identifizieren, was passiert ist Wenn Sie diese API-Methode so ändern, dass HTTP 200 zurückgegeben wird, wird die Abwärtskompatibilität insgesamt beeinträchtigt.

Ändern Sie niemals Parameter

Vermeiden Sie das Erstellen einer neuen Version der API, wenn Sie nur geringfügige Änderungen vornehmen, da dies möglicherweise zu viel des Guten ist. Ein besserer Ansatz besteht darin, Ihren API-Methoden Parameter hinzuzufügen, um das neue Verhalten zu berücksichtigen. Aus dem gleichen Grund sollten Sie keine Parameter aus einer API-Methode entfernen oder einen Parameter von optional in obligatorisch (oder umgekehrt) ändern, da diese Änderungen die API beschädigen und alte Clients oder Konsumenten der API nicht mehr in der Lage sind mit der API arbeiten.

Versionieren Sie Ihre API

Die Versionierung von APIs ist eine gute Vorgehensweise. Durch die Versionierung wird Ihre API flexibler und an Änderungen anpassbar, während die Funktionalität erhalten bleibt. Es hilft Ihnen auch dabei, Änderungen am Code besser zu verwalten und einfacher zum alten Code zurückzukehren, wenn der neue Code Probleme verursacht. Sie sollten mit jeder Hauptversion eine andere Version Ihrer RESTful-API haben.

Obwohl REST keine spezifischen Anleitungen zur API-Versionierung bietet, können Sie Ihre API auf drei verschiedene Arten versionieren: Angeben der Versionsinformationen im URI, Speichern der Versionsinformationen im benutzerdefinierten Anforderungsheader und Hinzufügen der Versionsinformationen zum HTTP-Akzeptieren Header. Obwohl die Versionierung Ihnen bei der Pflege Ihrer API helfen kann, sollten Sie vermeiden, viele Versionen der API zu pflegen, um häufige Releases zu kennzeichnen. Dies wird schnell umständlich und kontraproduktiv. 

Andere Best Practices für APIs

Sie sollten niemals die Stamm-URL einer API ändern oder die vorhandenen Abfragezeichenfolgenparameter ändern. Alle zusätzlichen Informationen sollten als optionaler Parameter zu einer API-Methode hinzugefügt werden. Sie sollten auch sicherstellen, dass optionale oder obligatorische Elemente, die an eine API übergeben oder von einer API zurückgegeben werden, niemals gelöscht werden.

Änderungen an einer RESTful-API sind unvermeidlich. Wenn Sie sich jedoch nicht an die Best Practices halten und sicherstellen, dass die API abwärtskompatibel ist, können Ihre Änderungen die Kompatibilität der API mit vorhandenen Clients beeinträchtigen. Eine API, die sich in der Produktion befindet und von mehreren Clients verwendet wird, sollte zwischen den Releases immer abwärtskompatibel sein.