Der eine oder andere mag die weit verbreitete Variante der API-Versionierung kennen, bei die Version in den Pfad eingebunden ist z.B. /v1/blog/posts. Das hat allerdings zur Folge, dass für jede neue Version ein neuer Pfad in der API eingepflegt wird. Die macht natürlich die Unterscheidung der Versionen einfacher, ist aber aus Entwicklersicht in manchen Fällen mit mehr Aufwand verbunden.
Eine Alternative die ich vor kurzem kennengelernt habe ist, die Version in den Accept-Header bzw. Content-Type zu integrieren z.b. „application/blogpost+v1.json“. Das bedeutet, dass sämtlich Versionen unter der gleichen URL erreicht werden können und die Logik bzw. die Response anhand des Accept-Headers anzupassen. Grundsätzlich ist der Gedanke dahinter identisch mit der der Version im Pfad, allerdings ermöglicht diese eine einfachere Weiterentwicklung ermöglicht.
Auch für die Consuming Services ist es so einfacher die neuen Versionen anzusprechen, da nur der Accept-Header verändert werden muss und nicht der Pfad.
Verschiedene Entity Types
Im gleichen Stil wie die Versionierung kann unter dem gleichen Pfad auch Logik für verschiedene Entity-Types einzubinden. Dies könnte z.B. so aussehen, dass unter der URL /blog über die Accept-Header „application/post+v1.json“ Informationen eines Blogartikels zurückgegeben werden, wenn nun als Accept-Header allerdings „application/tag+v1.json“ verwendet wird Informationen eines Tags zurückgegeben werden. Natürlich kann man an es mit dieser Technik auch übertreiben, weshalb dies vorsichtig und in Maßen angewendet werden sollte, so sollte der Pfad /blog auch nur Entity-Types im Blogumfeld zurückgeben und nicht zum Thema Shop oder ähnlichem. Gerade bei verschiedenen Entity-Types unter der gleichen Base ermöglicht es diese Technik nicht zahlreiche verschiedene Endpunkte erstellen zu müssen.
Umsetzung
Für die Umsetzung dieser Header gesteuerten Versionierung bzw. Typisierung kann z.B. Spring-Boot verwendet werden, was dies verhältnismäßig einfach macht. Das geht mit dieser Annotation:
@GetMapping(path = "/{reference}", produces = "application/blog.v1+json")Dies wird bei der Verwendung des gleichen Pfades auch in swagger (springdoc) korrekt angezeigt und es wir ein Dropdown erzeugt, welches die möglichen Response-Types enthält und so eine Auswahl ermöglicht. Gleiches gilt natürlich auch für Response Content-Types, welche nach dem gleichen Prinzip angezeigt werden.