>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 <mitchell...@gmail.com> 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 <robert.o.bu...@gmail.com> > 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 <mitchell...@apache.org> > > 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 > > > > > >
