@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 endpoi
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 wrote:
> Rawlin,
>
> I have submit
I am fine if we move in this direction, but I think we should be very
careful not to break existing functionality. We need to make sure that if
we do change from path params to query params that we update our API
versions, documentation, and tests accordingly.
Unless I am reading it wrong, it look
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
wrote:
> Do we currently have an example of a
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 wrote:
> Thank you John for giving us "API Use Cases" to
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
@jjrushford The practical value driving this, is that the Go standard
library's HTTP router can't do path matching. The same is likely true for
any simple language (e.g. C vs Java). Query parameters let us use the
built-in router, saving either a complex bit of routing code, or a large
third party
John,
TBH, it's hard to find any hard and fast rules regarding REST. At least I
haven't found any.
So the question is why B instead of A:
A. GET api/1.3/deliveryservices/{xmlID}/urisigning
B. GET api/1.3/deliveryservices_urisigningkeys[?optional queryParams]
I can think of a few reasons:
1. qu
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
Ah, sorry, I misunderstood. I thought when you said "a route that never
existed in 1.2 before" you meant e.g. /api/1.3/servers "didn't exist in
Golang or 1.3 before".
Right, for entirely new routes, e.g. deliveryservices/{xmlID}/urisignkeys,
path params are fine, and still conform to SemVer for th
You're right, in our code today, we don't use raw major versions
(/api/1/foo) in our API, and our clients have hard-coded minor versions.
If we feel like that's how we want to design APIs and clients, and say "our
minor versions are not compatible with each-other", we can do that. But
it's not Sem
" a request from a client which is built to understand say /api/1.2/, if
that same request is made to /api/1.3/, it should still work."
But this is a route that never existed in 1.2 before, not a new version of a
route in 1.3,
a client built to understand 1.2 will just not have this route at
>Technically, adding new routes does not break old stuff right so i don't
think that warrants a major version roll.
New routes that use query params instead of path params will definitely
break old stuff.
When you say "break old stuff", the idea behind Semantic Versioning, is
that a request from
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
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
w
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
16 matches
Mail list logo
