You're right, in our code today, we don't use raw major versions (/api/1/foo) in our API, and our clients have hard-coded minor versions.
If we feel like that's how we want to design APIs and clients, and say "our minor versions are not compatible with each-other", we can do that. But it's not Semantic Versioning. Semantic Versioning says: (semver.org) > MAJOR version when you make incompatible API changes, > MINOR version when you add functionality in a backwards-compatible manner Even if our current code doesn't strictly need SemVer, using a well-known standard makes it easier to understand. People know at a glance which versions are compatible, which have changed, and when they need to go read the docs again. Maybe someone else wants to write their own TO client, that expects SemVer. Is there a disadvantage to using SemVer? Even if we want to break backwards compatibility, we can just keep rolling major versions, /api/2/, /api/3/, /api/42/. I'd rather we didn't break compatibility so often, but if we do, there's no harm in the number itself. On Wed, Apr 4, 2018 at 4:00 PM, Volz, Dylan <[email protected]> wrote: > " a request from a client which is built to understand say /api/1.2/, if > that same request is made to /api/1.3/, it should still work." > > But this is a route that never existed in 1.2 before, not a new version of > a route in 1.3, > a client built to understand 1.2 will just not have this route at all and > would require > new dev work to support, or maybe I am misunderstanding you? > > On 4/4/18, 3:49 PM, "Robert Butts" <[email protected]> wrote: > > >Technically, adding new routes does not break old stuff right so i > don't > think that warrants a major version roll. > > New routes that use query params instead of path params will definitely > break old stuff. > > When you say "break old stuff", the idea behind Semantic Versioning, is > that a request from a client which is built to understand say > /api/1.2/, if > that same request is made to /api/1.3/, it should still work. If not, > it's > not Semantic Versioning. > > That also allows you to serve your latest minor version at /api/1/, > /api/2/, etc, and clients who know the Server is newer than them can > hit > the major endpoint, and be guaranteed to work. We don't currently do > that, > but it'd be nice if we did. > > I'm +1 on query params, but also +1 on https://semver.org/ > > > On Wed, Apr 4, 2018 at 3:23 PM, Jeremy Mitchell <[email protected] > > > wrote: > > > tbh i'm not sure about versioning. I was just trying to suggest that > new > > routes be formulated this way per the new API guidelines: > > > > GET /foos[?id, name, etc=] > > POST /foos > > PUT /foos [?id, name, etc=] > > DELETE /foos [?id, name, etc=] > > > > instead of the old way: > > > > GET /foos > > GET /foos/:id > > POST /foos > > PUT /foos/:id > > DELETE /foos/:id > > > > The difference being the use of query params over route/path params. > > > > Technically, adding new routes does not break old stuff right so i > don't > > think that warrants a major version roll. > > > > While we're on the subject, what does everyone think if we took this > one > > step further and made routes handle a request payload with one or > more > > items. For example: > > > > GET /foos[?id, name, etc=] > > POST /foos <-- takes in an array of foos to create > > PUT /foos <-- takes in an array of foos to update > > DELETE /foos <-- takes in an array of foos to delete > > > > in this scenario, query params only pertain to the GET. The POST, > PUT and > > DELETE rely on the contents of the request json... > > > > Jeremy > > > > > > > > > > > > > > > > > > > > > > > > On Wed, Apr 4, 2018 at 1:55 PM, Robert Butts < > [email protected]> > > wrote: > > > > > That document doesn't mention versions, 1.2 vs 1.3 vs 2.0. > > > > > > Just to clarify, changing to query parameters breaks compatibility > with > > 1.2 > > > and older, so new APIs in that format have to be a new major > version, > > i.e. > > > 2.0, per Semantic Versioning, right? > > > > > > On Tue, Apr 3, 2018 at 3:26 PM, Jeremy Mitchell < > [email protected]> > > > wrote: > > > > > > > FYI - I've updated the TO API guidelines to reflect our desire > to move > > > away > > > > from route/path params and embrace query params in the Golang > API. > > > > > > > > https://cwiki.apache.org/confluence/display/TC/API+Guidelines > > > > > > > > Jeremy > > > > > > > > > > > >
