API Versioning

[itchison]

Let me first off say, thank you for doing this collaboratively and for all the work that has gone into this.

I do find the versioning section to be very prescriptive. Versioning is hard. Our project currently releases every day and usually has API changes on every release. Not breaking changes, but usually small additions. We're starting to get third-party consumers and will version when we introduce a breaking change.

I feel versioning at this fidelity forces an event driven architecture which is an unneeded complexity for many applications.

Feel free to hit me up in the lab if you'd like to discuss more.

[stephenhillier]

I'd like to add my support here. I think it makes more sense to update/evolve v1, if non-breaking additions are required, and add v2 when breaking changes can no longer be avoided.

This will require a clear definition of exactly what changes require a new version (a removed field, a change in a field's format/type, change in functionality, etc.), for teams to commit to not break that contract, and for consumers to accept non-breaking changes (such as an addition of a field to a JSON response).

[jeff-card]

Thank you for your comment! A peer review was held on August 9th and we have the following feedback:

We agree the current wording may come across as prescriptive. This will be reworded and the approach slightly modified; the details of which are discussed in the next issue, as it is somewhat duplicative.