@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 <rawlin.pet...@gmail.com> 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 <mitchell...@gmail.com> > 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 <rawlin.pet...@gmail.com> > > 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 <dewr...@apache.org> > >> 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 <jjrushf...@gmail.com> > >> 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 <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 > >> >> >>> > >> >> >> > >> >> > >> >> > >> >
