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

Reply via email to