ocket8888 commented on issue #3023: WIP Supported routes fetch URL: https://github.com/apache/trafficcontrol/pull/3023#issuecomment-438464076 > 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" Because if at some point in the future it changes, then we have to either change `/api/1.2/routes` or it'll just be wrong and clients will break without knowing why. > 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` But isn't that exactly the problem we're trying to solve? We have truly reached versioning hell if I need versioning fallback for my version endpoint. Once I know whether `1.new/x` will succeed, I no longer need the version endpoint. > 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. IMO if you don't send an `Accept` (or send `Accept: *`) you're telling the server you don't care about the MIME of the response, and plaintext seems like the least complicated, most "default" MIME type, if that makes sense. > 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. If your response headers tell you the version of the server, then you instantly know the form of the response. I can't think of a good reason for the fundamental structure to change at any point in the near future. > 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. It's sort of beside the point, and it's definitely not true that _all_ of the confusion would vanish now that I think about it, but basically, yeah. If you're a user with limited understanding of programming, then you're not using the API, you're using Traffic Portal. every major revision would have no breaking changes until the next revision, so by definition x.y would be compatible with x.z for all y and z. We should probably support back a major version, but I wouldn't expect a client written for TC 1.0 to work with TC 3.0 Rolling major revs isn't really the issue as far as I'm concerned - that's not a big deal. The problem is I have no idea what API version any given server supports. If it's tied to the server version, then `Server: Traffic Operations/4.0.0` immediately tells me what's supported, without any need to list all the routes on the server.
---------------------------------------------------------------- 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
