> Consider the following pair of URLS: [/api/v1/posts/1, /api/v2/posts/1] This implies out-of-band information that these two resources are actually the same entity.
No, it doesn't imply that. Now, it would be accurate to say that it would require out-of-band information to know that the two resources are the same entity, but that's not true either. Assuming that the entity returned by a request to an API-specified endpoint has an API-independent GET-able representation, you can specify that in-band in any response that produces the entity using the Content-Location: response header.
> The version number belongs in the `Accept:` field of the HTTP request headers
No, it doesn't. This makes no sense, since Accept defines media types acceptable in the response, not the semantics of the request, whereas different API versions mean different request semantics.
Insofar as multiple representations of returned entities are available, it might make sense to use this style to differentiate which representation version the client wanted, but it doesn't make sense to specify the API version, since that may involve the representation expected by the server on client-sent bodies (for non-GET requests) rather than (or in addition to) changing the format of server-sent bodies, while the Accept: header is only about the latter, not the former.
No, it doesn't imply that. Now, it would be accurate to say that it would require out-of-band information to know that the two resources are the same entity, but that's not true either. Assuming that the entity returned by a request to an API-specified endpoint has an API-independent GET-able representation, you can specify that in-band in any response that produces the entity using the Content-Location: response header.
> The version number belongs in the `Accept:` field of the HTTP request headers
No, it doesn't. This makes no sense, since Accept defines media types acceptable in the response, not the semantics of the request, whereas different API versions mean different request semantics.
Insofar as multiple representations of returned entities are available, it might make sense to use this style to differentiate which representation version the client wanted, but it doesn't make sense to specify the API version, since that may involve the representation expected by the server on client-sent bodies (for non-GET requests) rather than (or in addition to) changing the format of server-sent bodies, while the Accept: header is only about the latter, not the former.