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