It's come up that our current versioning system may be overly complicated. If a user doesn't want the API to change underneath them, they'd have to set an Accept header to application/vnd.open511.v1+json, or include a ?format=application/vnd.open511.v1+json URL parameter. This might be verbose and confusing for new users.
Here's an alternate system that trades off some HTTP purity for increased simplicity:
As in the current system, versions are indicated by a version string, e.g. "v1", that changes when (and only when) backwards-incompatible differences are introduced
The Accept header now uses only generic content types, i.e. application/xml and application/json
Clients may provide an Open511-Version: v1 header to specify their preferred version
Clients may alternatively provide a ?version=v1 URL parameter
It's come up that our current versioning system may be overly complicated. If a user doesn't want the API to change underneath them, they'd have to set an
Acceptheader toapplication/vnd.open511.v1+json, or include a?format=application/vnd.open511.v1+jsonURL parameter. This might be verbose and confusing for new users.Here's an alternate system that trades off some HTTP purity for increased simplicity:
Acceptheader now uses only generic content types, i.e.application/xmlandapplication/jsonOpen511-Version: v1header to specify their preferred version?version=v1URL parameter