Welche Möglichkeiten gibt es?

Zu beachtende Punkte

  • Rückwärtskompatibität beachten
  • Major Versionen vermeiden

  • Vorwärtsrkompatibilität berücksichtigen

  • siehe dazu hier

3 Wege, es falsch zu machen

  1. Version in der URL lassen:
    • /api/v1/...
  2. Version im MediaType des Accept Header übertragen:
    • application/vnd.myname.v1+json oder application/vnd.myname+json; version=2
  3. Custom Request Header verwenden:
    • api-version: 2

URL

(+) durch Nutzung von HATEOAS wird der Client automatisch auf die neue Version geleitet
(-) URL wird länger
(-) wenn eine Änderung an einer Resource passiert, muss die gesamte API auf die neue Version gesetzt werden: /api/v2/.. (auch die Resourcen, die sich nicht geändert haben
(-) Cache muss mehrere Versionen der gleichen Resource haben
(-) Cache Invalidierung funktioniert nicht mehr über mehrere Versionen
(-) Clientcaching ist einfacher, da Caching mit URL als Key einfacher ist, als MediaType als Key\

Accept Header

(+) nur die Resourcen, die sich geändert haben, müssen in beiden Versionen vorhanden sein
(-) für das Caching muss ein Vary HTTP Header verwendet werden: siehe auch hier

Request Header

(-) die Resource ist jetzt nicht nur durch eine URL, sondern eine Kombination von URL + Header definiert
(+) URL der Resource ändert sich nicht