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 > >> >>> > >> >> > >> > >> >
