CodePark/ questions / Pagination, filtering & versioning
START PRACTICINGPRACTICE
Backend question · HTTP & API design › Pagination, filtering & versioning

What are the common ways to version an HTTP API, and what are their trade-offs?

There are three common ways.

URL path: /v1/orders. This is the most common. The version is visible. It is easy to route, to test in a browser and to cache. The cost: the version becomes part of every resource's URL.

Custom header: Api-Version: 2. URLs stay clean. But the costs are:

  • Clients easily forget the header.
  • It is harder to test quickly.
  • Caches need a Vary header on it, so they store each version separately.

Media type: Accept: application/vnd.shop.v2+json. This versions the response format through content negotiation (the client asks for a format, and the server picks it). It follows HTTP rules most strictly. But it is the least convenient for clients and tools.

Whatever you choose:

  • Create a new version only for breaking changes.
  • Make additive changes freely, without a new version.
  • Give old versions a deprecation timeline.
  • Announce deprecation in documentation and in headers.

NestJS supports URI, header and media type versioning out of the box.

  • URL path versioning is simple, visible and the most common.
  • Header versioning keeps URLs clean, but needs Vary and is easy to forget.
  • Media type versioning uses content negotiation and is the least convenient.
  • Create a new version only for breaking changes, and have a deprecation policy.