Re: Updated TO API guidelines
@dave - you're right. the PR referenced above did not update version, docs or tests. re: version - these were very new endpoints. i simply rewrote it to follow the new api guidelines. i think the risk of doing that was low as TP is the only consumer of this endpoint. re: docs - docs for 1.3 endpoints haven't been written. we're going to depend on swagger for that. right dewayne? re: tests - yep, i failed to update the existing tests and broke them and submitted this subsequent PR - https://github.com/apache/incubator-trafficcontrol/pull/2106 @rawlin - i agree. i'd love to dump support for the `?(.json) ` suffix. seems redundant. i would suggest that any new GET routes don't include it. On Mon, Apr 9, 2018 at 12:02 PM, Rawlin Peters wrote: > Thanks for the example, Jeremy. Do we have any guidelines about > whether or not the `?(.json) ` suffix should be supported for new API > endpoints? It seems pointless because the API will always return JSON. > > - Rawlin > > On Fri, Apr 6, 2018 at 3:14 PM, Jeremy Mitchell > wrote: > > Rawlin, > > > > I have submitted a PR to change some new ds request routes to utilize > query > > params instead of path/route params (the legacy format): > > > > https://github.com/apache/incubator-trafficcontrol/pull/2094 > > > > On Fri, Apr 6, 2018 at 11:59 AM, Rawlin Peters > > wrote: > > > >> Do we currently have an example of an API endpoint written in the > >> traffic_ops_golang framework that uses only query parameters like > >> this? How would it compare to the legacy format? > >> > >> -Rawlin > >> > >> On Thu, Apr 5, 2018 at 9:45 AM, Dewayne Richardson > >> wrote: > >> > Thank you John for giving us "API Use Cases" to think about with these > >> new > >> > TO API Guidelines. The main goal for these changes are to build TO > API's > >> > that are intuitive. I'm of the opinion that if the API's are > intuitive > >> > (with easy to understand patterns) that prevents me from wasting time > >> > looking up API docs. A nice side effect of having simple standards > and > >> > patterns is that simplicity ripples into our API Go code which allows > us > >> to > >> > easily build frameworks that do all of the work instead of the API > >> > snowflakes that we have today. > >> > > >> > I encourage everyone to shoot as many holes into our thoughts around > this > >> > new direction so that we can see the bigger picture. > >> > > >> > -Dew > >> > > >> > On Wed, Apr 4, 2018 at 10:29 PM, John Rushford > >> wrote: > >> > > >> >> Why the change? It’s my understanding that path parameters should be > >> used > >> >> to specify a particular resource > >> >> and query parameters should be used to sort/filter the query. Why > use a > >> >> query parameter to specify a particular > >> >> resource? Is this REST API best practice? > >> >> > >> >> What about sub resource queries such as using the following: > >> >> > >> >> GET api/1.3/deliveryservices/{xmlID}/urisigning > >> >> > >> >> where you are requesting a particular urisigning keys sub resource > for > >> the > >> >> particular deliveryservice resource. You can make it work > >> >> with an xmlid query parameter but what do you return if the query > >> >> parameter is left off, all uri signing keys? Is that useful? > >> >> > >> >> John > >> >> > >> >> > On Apr 4, 2018, at 3:23 PM, Jeremy Mitchell > > >> >> 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
Re: Updated TO API guidelines
Thanks for the example, Jeremy. Do we have any guidelines about whether or not the `?(.json) ` suffix should be supported for new API endpoints? It seems pointless because the API will always return JSON. - Rawlin On Fri, Apr 6, 2018 at 3:14 PM, Jeremy Mitchell wrote: > Rawlin, > > I have submitted a PR to change some new ds request routes to utilize query > params instead of path/route params (the legacy format): > > https://github.com/apache/incubator-trafficcontrol/pull/2094 > > On Fri, Apr 6, 2018 at 11:59 AM, Rawlin Peters > wrote: > >> Do we currently have an example of an API endpoint written in the >> traffic_ops_golang framework that uses only query parameters like >> this? How would it compare to the legacy format? >> >> -Rawlin >> >> On Thu, Apr 5, 2018 at 9:45 AM, Dewayne Richardson >> wrote: >> > Thank you John for giving us "API Use Cases" to think about with these >> new >> > TO API Guidelines. The main goal for these changes are to build TO API's >> > that are intuitive. I'm of the opinion that if the API's are intuitive >> > (with easy to understand patterns) that prevents me from wasting time >> > looking up API docs. A nice side effect of having simple standards and >> > patterns is that simplicity ripples into our API Go code which allows us >> to >> > easily build frameworks that do all of the work instead of the API >> > snowflakes that we have today. >> > >> > I encourage everyone to shoot as many holes into our thoughts around this >> > new direction so that we can see the bigger picture. >> > >> > -Dew >> > >> > On Wed, Apr 4, 2018 at 10:29 PM, John Rushford >> wrote: >> > >> >> Why the change? It’s my understanding that path parameters should be >> used >> >> to specify a particular resource >> >> and query parameters should be used to sort/filter the query. Why use a >> >> query parameter to specify a particular >> >> resource? Is this REST API best practice? >> >> >> >> What about sub resource queries such as using the following: >> >> >> >> GET api/1.3/deliveryservices/{xmlID}/urisigning >> >> >> >> where you are requesting a particular urisigning keys sub resource for >> the >> >> particular deliveryservice resource. You can make it work >> >> with an xmlid query parameter but what do you return if the query >> >> parameter is left off, all uri signing keys? Is that useful? >> >> >> >> John >> >> >> >> > On Apr 4, 2018, at 3:23 PM, Jeremy Mitchell >> >> 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 >> >> >>> >> >> >> >> >> >> >> >>
Re: Updated TO API guidelines
I am fine if we move in this direction, but I think we should be very careful not to break existing functionality. We need to make sure that if we do change from path params to query params that we update our API versions, documentation, and tests accordingly. Unless I am reading it wrong, it looks like the PR mentioned above by Jeremy is not updating the version, the docs, or any associated tests. Thanks, Dave On Fri, Apr 6, 2018 at 3:14 PM, Jeremy Mitchell wrote: > Rawlin, > > I have submitted a PR to change some new ds request routes to utilize query > params instead of path/route params (the legacy format): > > https://github.com/apache/incubator-trafficcontrol/pull/2094 > > On Fri, Apr 6, 2018 at 11:59 AM, Rawlin Peters > wrote: > > > Do we currently have an example of an API endpoint written in the > > traffic_ops_golang framework that uses only query parameters like > > this? How would it compare to the legacy format? > > > > -Rawlin > > > > On Thu, Apr 5, 2018 at 9:45 AM, Dewayne Richardson > > wrote: > > > Thank you John for giving us "API Use Cases" to think about with these > > new > > > TO API Guidelines. The main goal for these changes are to build TO > API's > > > that are intuitive. I'm of the opinion that if the API's are intuitive > > > (with easy to understand patterns) that prevents me from wasting time > > > looking up API docs. A nice side effect of having simple standards and > > > patterns is that simplicity ripples into our API Go code which allows > us > > to > > > easily build frameworks that do all of the work instead of the API > > > snowflakes that we have today. > > > > > > I encourage everyone to shoot as many holes into our thoughts around > this > > > new direction so that we can see the bigger picture. > > > > > > -Dew > > > > > > On Wed, Apr 4, 2018 at 10:29 PM, John Rushford > > wrote: > > > > > >> Why the change? It’s my understanding that path parameters should be > > used > > >> to specify a particular resource > > >> and query parameters should be used to sort/filter the query. Why > use a > > >> query parameter to specify a particular > > >> resource? Is this REST API best practice? > > >> > > >> What about sub resource queries such as using the following: > > >> > > >> GET api/1.3/deliveryservices/{xmlID}/urisigning > > >> > > >> where you are requesting a particular urisigning keys sub resource for > > the > > >> particular deliveryservice resource. You can make it work > > >> with an xmlid query parameter but what do you return if the query > > >> parameter is left off, all uri signing keys? Is that useful? > > >> > > >> John > > >> > > >> > On Apr 4, 2018, at 3:23 PM, Jeremy Mitchell > > >> 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 > > >> >>> > > >> >> > > >>
Re: Updated TO API guidelines
Rawlin, I have submitted a PR to change some new ds request routes to utilize query params instead of path/route params (the legacy format): https://github.com/apache/incubator-trafficcontrol/pull/2094 On Fri, Apr 6, 2018 at 11:59 AM, Rawlin Peters wrote: > Do we currently have an example of an API endpoint written in the > traffic_ops_golang framework that uses only query parameters like > this? How would it compare to the legacy format? > > -Rawlin > > On Thu, Apr 5, 2018 at 9:45 AM, Dewayne Richardson > wrote: > > Thank you John for giving us "API Use Cases" to think about with these > new > > TO API Guidelines. The main goal for these changes are to build TO API's > > that are intuitive. I'm of the opinion that if the API's are intuitive > > (with easy to understand patterns) that prevents me from wasting time > > looking up API docs. A nice side effect of having simple standards and > > patterns is that simplicity ripples into our API Go code which allows us > to > > easily build frameworks that do all of the work instead of the API > > snowflakes that we have today. > > > > I encourage everyone to shoot as many holes into our thoughts around this > > new direction so that we can see the bigger picture. > > > > -Dew > > > > On Wed, Apr 4, 2018 at 10:29 PM, John Rushford > wrote: > > > >> Why the change? It’s my understanding that path parameters should be > used > >> to specify a particular resource > >> and query parameters should be used to sort/filter the query. Why use a > >> query parameter to specify a particular > >> resource? Is this REST API best practice? > >> > >> What about sub resource queries such as using the following: > >> > >> GET api/1.3/deliveryservices/{xmlID}/urisigning > >> > >> where you are requesting a particular urisigning keys sub resource for > the > >> particular deliveryservice resource. You can make it work > >> with an xmlid query parameter but what do you return if the query > >> parameter is left off, all uri signing keys? Is that useful? > >> > >> John > >> > >> > On Apr 4, 2018, at 3:23 PM, Jeremy Mitchell > >> 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 > >> >>> > >> >> > >> > >> >
Re: Updated TO API guidelines
Do we currently have an example of an API endpoint written in the traffic_ops_golang framework that uses only query parameters like this? How would it compare to the legacy format? -Rawlin On Thu, Apr 5, 2018 at 9:45 AM, Dewayne Richardson wrote: > Thank you John for giving us "API Use Cases" to think about with these new > TO API Guidelines. The main goal for these changes are to build TO API's > that are intuitive. I'm of the opinion that if the API's are intuitive > (with easy to understand patterns) that prevents me from wasting time > looking up API docs. A nice side effect of having simple standards and > patterns is that simplicity ripples into our API Go code which allows us to > easily build frameworks that do all of the work instead of the API > snowflakes that we have today. > > I encourage everyone to shoot as many holes into our thoughts around this > new direction so that we can see the bigger picture. > > -Dew > > On Wed, Apr 4, 2018 at 10:29 PM, John Rushford wrote: > >> Why the change? It’s my understanding that path parameters should be used >> to specify a particular resource >> and query parameters should be used to sort/filter the query. Why use a >> query parameter to specify a particular >> resource? Is this REST API best practice? >> >> What about sub resource queries such as using the following: >> >> GET api/1.3/deliveryservices/{xmlID}/urisigning >> >> where you are requesting a particular urisigning keys sub resource for the >> particular deliveryservice resource. You can make it work >> with an xmlid query parameter but what do you return if the query >> parameter is left off, all uri signing keys? Is that useful? >> >> John >> >> > On Apr 4, 2018, at 3:23 PM, Jeremy Mitchell >> 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 >> > 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 > > >> >> 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 >> >>> >> >> >> >>
Re: Updated TO API guidelines
Thank you John for giving us "API Use Cases" to think about with these new TO API Guidelines. The main goal for these changes are to build TO API's that are intuitive. I'm of the opinion that if the API's are intuitive (with easy to understand patterns) that prevents me from wasting time looking up API docs. A nice side effect of having simple standards and patterns is that simplicity ripples into our API Go code which allows us to easily build frameworks that do all of the work instead of the API snowflakes that we have today. I encourage everyone to shoot as many holes into our thoughts around this new direction so that we can see the bigger picture. -Dew On Wed, Apr 4, 2018 at 10:29 PM, John Rushford wrote: > Why the change? It’s my understanding that path parameters should be used > to specify a particular resource > and query parameters should be used to sort/filter the query. Why use a > query parameter to specify a particular > resource? Is this REST API best practice? > > What about sub resource queries such as using the following: > > GET api/1.3/deliveryservices/{xmlID}/urisigning > > where you are requesting a particular urisigning keys sub resource for the > particular deliveryservice resource. You can make it work > with an xmlid query parameter but what do you return if the query > parameter is left off, all uri signing keys? Is that useful? > > John > > > On Apr 4, 2018, at 3:23 PM, Jeremy Mitchell > 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 > > 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 > > >> 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 > >>> > >> > >
Re: Updated TO API guidelines
@jjrushford The practical value driving this, is that the Go standard library's HTTP router can't do path matching. The same is likely true for any simple language (e.g. C vs Java). Query parameters let us use the built-in router, saving either a complex bit of routing code, or a large third party library. They should also be faster, if performance matters. Most routers use the easier regex matching, which can be slow. Go's standard router iterates over all routes and does a string comparison on every one, for every request. Fast methods exist, like a trie, but they're complex to implement and maintain. While query params are put in a hashmap passed to the request handler. In terms of ideology, you're right, the widely-accepted practice is for path parameters to specify a "resource," and for query params to "filter." That said, there's nothing in any RFC condoning or requiring that, as far as I'm aware. (RFC3986 says "The query component contains non-hierarchical data that, along with data in the path component (Section 3.3), serves to identify a resource".) > what do you return if the query parameter is left off A 4xx, same as if they omitted the path field. >I know there have been a lot of complaints about having to fetch resources by id instead of name. This will take care of that. @mitchell852 +1. Getting rid of IDs in the database and using real data as keys will be even better, if we can ever get to that point. But that's a different discussion. Also to @mitchell852 's point on ambiguity, paths make compound keys unintuitive, too. For example, is it /api/profile-parameters/foo/bar, or /api/profile-parameters/bar/foo, or /api/profile-parameters/profile/foo/parameter/bar, or /api/profile-parameters/parameter/bar/profile/foo, or /api/profile/foo/parameter/bar, or /api/parameter/bar/profile/foo, or /api/profile/foo/bar? You could guess, but there's no unambiguously obvious right answer, you'd have to look up the docs. Whereas with query params, /api/profile-parameters?profile=foo¶meter=bar is obvious. Maybe another way to think about it, for the ideological "resource", is that the database table (or view) is the resource, and the query params are filtering that table how you want. Personally, I'm inclined to put the practical above the ideological in this case. But I don't care enough to fight for it. A regex router in Go is 50 lines of code; it's 50 complex lines, but it's 50 lines. If other people have strong opinions, I'll step back. On Thu, Apr 5, 2018 at 8:50 AM, Jeremy Mitchell wrote: > John, > > TBH, it's hard to find any hard and fast rules regarding REST. At least I > haven't found any. > > So the question is why B instead of A: > > A. GET api/1.3/deliveryservices/{xmlID}/urisigning > B. GET api/1.3/deliveryservices_urisigningkeys[?optional queryParams] > > I can think of a few reasons: > > 1. query params are unambiguous. for example, they look like ?xmlId=foobar. > there is a key and a value. looking at > api/1.3/deliveryservices/foobar/urisigning, > it may not be clear that foobar is the xmlId of the delivery service. > 2. pattern matching can get screwed up. think of this example. we have 2 > routes defined: > > GET /foos/:id > GET /foos/:name > > which route does this match? GET /foos/42 > > maybe names can be numbers. so is 42 an ID or a Name? not sure. > > 3. we can get away with less route definitions. instead of 3 routes: > > GET /foos <-- get all foos > GET /foos/:id <-- get foo by id > GET /foos/:name <-- get foo by name > > we can simply have 1: > > GET /foos with optional query params (?id= or ?name=) > > I know there have been a lot of complaints about having to fetch resources > by id instead of name. This will take care of that. > > 4. Nested routes can start to get a little nasty and uneccessary imo. GET > /foos/:id/bars/:id/comments/:id (there can be a lot of permutations of > that) where you really only need the id of the comment to retrieve it: GET > /foo_bar_comments?id=4 > > 5. There are some built in benefits in Go but I'll have to defer to Rob > and/or Dylan regarding that. > > Off the top of my head, that's all i can think of. If we plan to use tools > such as Swagger for our API, we need to agree on a standard for the API and > stick to it. We're simply trying to find that standard. :) > > Jeremy > > > > > > On Wed, Apr 4, 2018 at 10:29 PM, John Rushford > wrote: > > > Why the change? It’s my understanding that path parameters should be > used > > to specify a particular resource > > and query parameters should be used to sort/filter the query. Why use a > > query parameter to specify a particular > > resource? Is this REST API best practice? > > > > What about sub resource queries such as using the following: > > > > GET api/1.3/deliveryservices/{xmlID}/urisigning > > > > where you are requesting a particular urisigning keys sub resource for > the > > particular deliveryservice resource. You can make it work > > with an xmlid query parameter but what do
Re: Updated TO API guidelines
John, TBH, it's hard to find any hard and fast rules regarding REST. At least I haven't found any. So the question is why B instead of A: A. GET api/1.3/deliveryservices/{xmlID}/urisigning B. GET api/1.3/deliveryservices_urisigningkeys[?optional queryParams] I can think of a few reasons: 1. query params are unambiguous. for example, they look like ?xmlId=foobar. there is a key and a value. looking at api/1.3/deliveryservices/foobar/urisigning, it may not be clear that foobar is the xmlId of the delivery service. 2. pattern matching can get screwed up. think of this example. we have 2 routes defined: GET /foos/:id GET /foos/:name which route does this match? GET /foos/42 maybe names can be numbers. so is 42 an ID or a Name? not sure. 3. we can get away with less route definitions. instead of 3 routes: GET /foos <-- get all foos GET /foos/:id <-- get foo by id GET /foos/:name <-- get foo by name we can simply have 1: GET /foos with optional query params (?id= or ?name=) I know there have been a lot of complaints about having to fetch resources by id instead of name. This will take care of that. 4. Nested routes can start to get a little nasty and uneccessary imo. GET /foos/:id/bars/:id/comments/:id (there can be a lot of permutations of that) where you really only need the id of the comment to retrieve it: GET /foo_bar_comments?id=4 5. There are some built in benefits in Go but I'll have to defer to Rob and/or Dylan regarding that. Off the top of my head, that's all i can think of. If we plan to use tools such as Swagger for our API, we need to agree on a standard for the API and stick to it. We're simply trying to find that standard. :) Jeremy On Wed, Apr 4, 2018 at 10:29 PM, John Rushford wrote: > Why the change? It’s my understanding that path parameters should be used > to specify a particular resource > and query parameters should be used to sort/filter the query. Why use a > query parameter to specify a particular > resource? Is this REST API best practice? > > What about sub resource queries such as using the following: > > GET api/1.3/deliveryservices/{xmlID}/urisigning > > where you are requesting a particular urisigning keys sub resource for the > particular deliveryservice resource. You can make it work > with an xmlid query parameter but what do you return if the query > parameter is left off, all uri signing keys? Is that useful? > > John > > > On Apr 4, 2018, at 3:23 PM, Jeremy Mitchell > 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 > > 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 > > >> 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 > >>> > >> > >
Re: Updated TO API guidelines
Why the change? It’s my understanding that path parameters should be used to specify a particular resource and query parameters should be used to sort/filter the query. Why use a query parameter to specify a particular resource? Is this REST API best practice? What about sub resource queries such as using the following: GET api/1.3/deliveryservices/{xmlID}/urisigning where you are requesting a particular urisigning keys sub resource for the particular deliveryservice resource. You can make it work with an xmlid query parameter but what do you return if the query parameter is left off, all uri signing keys? Is that useful? John > On Apr 4, 2018, at 3:23 PM, Jeremy Mitchell 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 > 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 >> 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 >>> >>
Re: Updated TO API guidelines
Ah, sorry, I misunderstood. I thought when you said "a route that never existed in 1.2 before" you meant e.g. /api/1.3/servers "didn't exist in Golang or 1.3 before". Right, for entirely new routes, e.g. deliveryservices/{xmlID}/urisignkeys, path params are fine, and still conform to SemVer for the same major version, e.g. 1.3. On Wed, Apr 4, 2018 at 4:12 PM, Robert Butts wrote: > 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 > 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" 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 < >> 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
Re: Updated TO API guidelines
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 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" 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 > > 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 > > > > > > > > > > > >
Re: Updated TO API guidelines
" 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" 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 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 > 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 > > 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 > > > > > >
Re: Updated TO API guidelines
>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 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 > 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 > > 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 > > > > > >
Re: Updated TO API guidelines
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 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 > 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 > > >
Re: Updated TO API guidelines
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 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 >