rob05c commented on issue #3023: WIP Supported routes fetch URL: https://github.com/apache/trafficcontrol/pull/3023#issuecomment-438452579 >Placing it under a versioned route will, first of all, cause the API definition of previous versions change Why do you think that? We can define a route, say `/api/1.2/routes` as "returns all routes served by this server across all versions". Nothing wrong with that. Sure, it feels odd, but there are no practical issues. >secondly will replace the "N+1" problem with the "chicken and egg" problem. If I don't know what versions the API has, I'm forced to try /api/1.0/api-routes and when that 404's I'm back where we are today, so it's already effectively version-less because only one version could possibly be useful. Sort of. That's what I was suggesting: you're right, users will be compelled to use the minimum version,`/api/1.0/api-routes`. But, why would we ever change that endpoint? Answer: if there's a critical design flaw. In which case, we add `/api/1.new/api-routes` to address the flaw. If the flaw is not security related, we still serve `/api/1.0/api-routes`, which itself includes `/api/1.new/api-routes`. Clients then have a choice: they can optimistically assume `1.new/api-routes`, and if it returns a 404, then realize the server is old and try `1.0/api-routes`. Or, they can start with the old one, and hit the new one if it's returned inside `1.0/api-routes`. If the flaw is security related, we change `/api/1.0/api-routes` to return `410 Gone`, which we document as signalling clients to try `/api/1.new/api-routes`. Old clients break, but that's inevitable with a security issue; and new clients retry. >Rather than change the output to JSON, I'd prefer to just implement content negotiation. I still think the relationships and data being represented are too simple to use JSON by default, but if a client expects JSON they should send Accept: application/json and the endpoint should probably support that. I'd support respecting `Accept` headers. And I agree in principle that this endpoint is better as plaintext, since it doesn't need the structure. But because the rest of our API is JSON, it's better to conform to that, and serve JSON by default, unless there's an `Accept` header for something else. It would be strange and unexpected to have our API be JSON by default, for all but one endpoint. At least for GET; I could buy the argument that if we did OPTIONS, it's ok since it's a separate method. >I don't understand why not versioning the api/ endpoint would in any way inhibit our ability to fix anything later. It should be as simple as adding With a fundamental change to the structure? Then old clients would break horribly, with no way of knowing why they even broke (because they're older than the change). New clients could potentially try to parse in multiple ways, until one succeeds, at both terrible cost and the inability to distinguish which version is actually malformed. That's why versioning exists. >FWIW all of this confusion would vanish if we tied the API version to the Traffic Ops version. How? We would have to roll the TC version for any API change, and vica-versa. There are advantages and disadvantages of tying the versions together, but this isn't one of them. We would have the exact same problems, and any change to this API endpoint in particular would require the exact same version rolls. Or you couldn't roll the version, if we didn't version some endpoints. Or are you suggesting the API not serve older versions at all? And only serve the latest version with TC? IMO that's completely unacceptable. That makes operator and developer lives easier, at the cost of astronomically increasing the difficulty for CDN clients, tenants, and Self-Service customers, many of whom may have very limited understanding of programming or software engineering.
---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
