Best Practice: Versionierung von REST Services

Rest Services haben sich mittlerweile weit verbreitet. Sie sind einfach zu erstellen und sehr leicht aufzurufen und basieren auf dem HTTP Protokoll. Bei WOGRA gehört die Entwicklung von REST Services zum täglichen Geschäft. Viele unserer Kunden verwenden die REST Services nicht nur intern für ihre eigenen Applikationen, sondern stellen diese anderen Partnern oder einer breiten Anwenderschaft zur Verfügung und wissen oftmals nicht, wer den Service überhaupt verwendet. Wenn nun ein Service erweitert bzw. verändert wird, kann es schnell passieren, dass dieser nicht wie gewünscht reagiert und die Umsysteme plötzlich vor Schwierigkeiten stehen.

Versionierung von REST Services

Aus diesem Grund haben wir bei WOGRA für die REST Service Implementierung bei unseren Kunden zwei Mechanismen eingeführt, die sicherstellen, dass die Versionierungshölle beherrschbar wird.

Der erste Schritt ist, dass wir in der URL unseres REST Service immer eine Versionsnummer mitgeben.

Beispiel: http://www.meinedomain.de:8080/rest/v1/einservice

Ist eine Version (im o.g. Beispiel v1) offiziell zur Anwendung freigegeben worden werden die Aufrufparameter eingefroren, sodass die Anwender sich darauf verlassen können, dass diese sich nicht mehr ändern. Das Ergebnis des REST Service darf um weitere Informationen erweitert werden, aber bestehende Informationen dürfen nicht weggelassen bzw. in ihrem Format geändert werden. Sollte dies notwendig werden, muss ein neuer Service geschrieben werden, oder Alternativ die Versionsnummer erhöht werden.

Damit haben wir schon mal das Ziel erreicht, dass die Schnittstelle zu den Umsystemen stabil bleibt und diese weiterhin verwendet werden können. Nun ergibt sich aber bei der weiteren Entwicklung das Problem, dass man nicht ständig alte Schnittstellen im System halten und warten will. Ab einem gewissen Zeitpunkt macht es einfach Sinn, alte Schnittstellen aus dem System zu entfernen. Da entsteht aber das nächste Problem. Wie will ich die Betreiber der Umsysteme, die meine alten Services nutzen, darüber informieren, dass diese abgeschalten werden, wenn ich die Betreiber gar nicht kenne? Das ist manchmal schon innerhalb großer Konzerne schwierig, aber wenn mein REST Service für jeden frei zugänglich ist, schier unmöglich.

Registrierung von Betreibern

Aus diesem Grund bauen wir bei unseren REST Services immer einen Token Mechanismus ein. Das bedeutet, dass ein Umsystem, dass meinen REST Service verwenden will, einen Token beantragen muss und diesen als Parameter im Aufruf mitgeben muss. Bei der Beantragung des Tokens speichert man sich Ansprechpartner und E-Mail Adresse des Anwenders und generiert ein Token, das zusätzlich in einer Konfigurationsdatei oder Datenbank gespeichert wird. So hat man die Kontaktdaten des Nutzers und ist in der Lage ihn zu informieren, falls sich etwas an der Schnittstelle ändert. Die Beantragung eines Tokens kann übrigens auch als REST Service implementiert werden, sodass möglichst wenig manueller Aufwand entsteht. Selbstverständlich kann es dann passieren, dass jemand eine falsche E-Mail Adresse oder den falschen Asnprechpartner angibt. Aber zum einen ist dieser dann selbst Schuld, wenn er nicht mitbekommt, dass sich der Service ändert und zum anderen könnte man einen zusätzlichen Registrierungsmechanismus einbauen. Die einfachste Lösung einen Token zu generieren ist der UUID Mechanismus.

Der Request vom Umsystem muss einfach um den Token erweitert werden. Ein Beispiel könnte wie folgt aussehen:

Beispiel: http://www.meinedomain.de:8080/rest/v1/einservice?token=<token>

Der beschriebene Mechanismus ist innerhalb kürzester Zeit (max. 2 Tage) implementiert. Wichtig ist, dass er von Beginn an vorgesehen ist, sonst handelt man sich mit seinen REST Services eventuell Ärger ein, den man vermeiden kann.

Erweiterungen

Für die meisten einfachen Fälle ist dieser Mechanismus ausreichend. Er reicht nicht mehr aus, wenn man wirklich den Zugriff auf das System schützen will. Sei es, dass Unbefugte nicht darauf zugreifen sollen, oder dass ein PayPerUse Abrechnungssystem integriert werden soll. Sollten Sie hier weitere Informationen benötigen, können Sie gerne mit uns Kontakt aufnehmen.