URLによるバージョニングは、/v2/ordersのように、バージョンをパスに置きます。バージョンが見えやすく、ルーティングも単純ですが、バージョンが変わるたびに、すべてのリソースのURLが変わります。

ヘッダーによるバージョニングは、Accept: application/vnd.api+json;version=2のように、バージョンをリクエストヘッダーに置きます。バージョンが変わっても、リソースのURLは同じままですが、URL自体にバージョンがある場合ほど、バージョンは見えやすくありません。

どちらの方式でも、目指すのは、新しいバージョンが必要になる頻度を、最小限にすることです。すべての変更が、新しいバージョンを必要とするわけではありません。

サーバーが、新しい任意項目のフィールドを追加しても、既存のクライアントは、変更なしに動き続けるため、非破壊的です。一方、フィールドを削除したり、型を変えたりすると、既存のクライアントがすでに頼っている前提が壊れるため、破壊的です。