Re: Updated TO API guidelines

@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

Re: Updated TO API guidelines

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

Re: Updated TO API guidelines

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

Re: Updated TO API guidelines

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

Re: Updated TO API guidelines

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

Re: Updated TO API guidelines

@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

Re: Updated TO API guidelines

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.

Re: Updated TO API guidelines

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

Re: Updated TO API guidelines

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

Re: Updated TO API guidelines

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

Re: Updated TO API guidelines

>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

Re: Updated TO API guidelines

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

Re: Updated TO API guidelines

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