His argument is for API discoverability. Client should be able to learn about available endpoints
[edit: ...and resources. And be able to comprehend resource record conventions]
Re:How to Version an API
by deathanatos on Friday June 09, 2017 @03:18PM
(#14523692)
I also don't see the point of API discoverability, at least, not programmatically. Sure, such a thing could be built, but I don't know what could be done w/ the results. Most API's I've ever worked on required domain knowledge in order to operate on (e.g., you had to understand the content — semantically — of the result. I.e., you needed to understand what a `applicaiton/vnd.bigcorp.widget.v2+json` was.)
I just don't see any generic operations w.r.t. discovery that are … useful.
I'm not trying to say that you shouldn't, e.g., use URLs in your resulting resources; e.g., if a query for a widget returns:
{
"widget_name": "NextGen Enterprise Widget",
"suppliers": "http://bigcorp.example.com/widget/123/suppliers"
}
That's fine. But you're still going to need to know how to parse the result of …/suppliers, or it's just opaque bytes.
The hostname thing might work for huge, world-changing re-writes, but for small, incremental changes, I think something like what GitHub does w/ the Accept header is far more appropriate.