API Versionierung

Zur Versionierung der Schnittstelle wird eine simple URL basierte Versionierung eingesetzt, da sowohl die die Anzahl der Nutzer, als auch die zu erwartenden Änderungen überschaubar sind.

Da bei einer Änderung der URL sämtliche Clients angepasst werden müssen, ist solch ein Update immer ein Major Update im Sinne des semantic versioning. Daher wird auch nur die Major Version in die URL aufgenommen. Sie hat dann das Format:

https://<URL Empfänger>/rd/v<API-Major-Version>/…

Die URL für die Major Version 2.x.x der API lautet dann z.B. : https://www.landeskrebsregister.nrw/rd/v2/...

Beispiele für Major Updates, die eine Versionsänderung in der URL zur Folge haben:

• Nicht mehr unterstützte Ressourcen oder Methoden

• Umbenennung einer Ressource oder ihrer bestehenden Attribute

Beispiele für Minor oder Patch Updates ohne Versionsänderung in der URL sind dagegen:

• Zusätzliche optionale Felder in einer Ressource

• Neue zusätzliche Ressourcen

Bei Minor oder Patch Updates wird lediglich die API Dokumentation erweitert, aber keine URL Änderung vorgenommen.