API versioning: per resource or across all APIs?

akoo
Participant V

Hey everyone,

A while back I made a comment on a thread on API versioning here:

https://community.apigee.com/questions/2271/api-versioning.html#comment-2570

Assuming we do want to version our API, and for sake of discussion, let's just assume we will do this through the URI. Do you think it's more appropriate to version across all APIs or per resource?

Here are the pros for each approach. Would be great to get your input:

Pro across all APIs:

  1. Clarifies compatibility -- /v2/orders should work with /v2/carts. Does /v2/orders work with /v1/carts? This aspect is unclear if we version per resource.
  2. Deprecation of resources is clearer. E.g., we can clearly state that v1 of all APIs will be deprecated in 6 months when v1 is across all APIs. We couldn't do the same as clearly if we versions per resource (e.g., v1 of orders is deprecated in 6 months, but v1 of carts won't be deprecated? This is confusing).

Pros per resource:

  1. Allows the API development team to version APIs as needed without affecting other unchanging APIs. This fits more into a microservices architecture by not forcing all APIs to be versioned at once (which could be a scheduling nightmare, if even impossible).
  2. If only the orders resource needs a new version (i.e., /v2/orders) and other APIs have not changed, versioning per resource does not lead to potential app changes for unaffected resources (e.g., an app that only uses carts can still use /v1/carts).
1 1 373
1 REPLY 1

Not applicable

You hem me in too much with your givens!

For the interdependency reasons you outline above I favor course grained versioning - meaning version all the resources in an API at once (even if only a subset have been modified). In this way you avoid the partial deprecation and interaction problems inherent in having fine grained resource versions.

As API designers we may need to confront this problem as platforms and practices evolve.