With the last couple weeks of changes, the API isn't the same /v1 as it was a month ago. It's also not exactly a /v2. This leads to needing the API to be backwards compatible and increases the likelihood of a change breaking clients, since they're still hitting /v1/some/path, which could have breaking changes on accident.
I propose we use a header, Accept-Version (or similar), that will guard new/changing/breaking behavior on the server. This makes changes to the server less likely to break things for older clients, and makes it easy to opt into new behavior. I'm partial to the value of the header being the date in YYYY-MM-DD format, since it's easy to keep track of and easy when implementing changes - just guard it behind
if (headers['Accept-Version'] >= today) { // when implementing the change, just put today's date
// whatever changes
}
With the last couple weeks of changes, the API isn't the same
/v1as it was a month ago. It's also not exactly a/v2. This leads to needing the API to be backwards compatible and increases the likelihood of a change breaking clients, since they're still hitting/v1/some/path, which could have breaking changes on accident.I propose we use a header,
Accept-Version(or similar), that will guard new/changing/breaking behavior on the server. This makes changes to the server less likely to break things for older clients, and makes it easy to opt into new behavior. I'm partial to the value of the header being the date inYYYY-MM-DDformat, since it's easy to keep track of and easy when implementing changes - just guard it behind