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 <[email protected]> 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 <[email protected]> > 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 <[email protected]> >> 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 <[email protected]> >> 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 <[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 >> >> >>> >> >> >> >> >> >> >> >>
