3 ms·

Encoding the version number in the URL may be convenient, but certainly does not follow REST. Consider the following pair of URLS: /api/v1/posts/1 /ap

by zedr 14y ago

Encoding the version number in the URL may be convenient, but certainly does not follow REST. 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. The version number belongs in the `Accept:` field of the HTTP request headers; for example `Accept: application/json; version=2`

buro9 14y ago
That's OK, the title of the article says "RESTful" and not "REST". Pragmatically I've found through experience that most developers tend to be more comfortable thinking of URLs and general content types.
mnarayan01 14y ago
Accept: application/json; version=2 Is that a standard-compliant media type? `version` doesn't appear to be associated with application/json in the IANA media type registry, and I couldn't find anything definitive about adding arbitrary parameters.
- masklinn 14y ago
  I'm pretty sure parameters are not limited to those provided by IANA (just as media types are not necessarily IANA-registered incidentally) e.g. RFC2616's Accept doc shows a `level` parameter to text/html which is not IANA-specified (and seems entirely unspecified)
  - mnarayan01 14y ago
    Yea I saw the use of level in the example but didn't think to look at the text/html spec to see if it was there. That would seem to imply that you are correct (though it would be nice if there were an explicit answer on this, if only for purely OCD reasons). > just as media types are not necessarily IANA-registered incidentally Per RFC4288 I believe they must be if they are in the standard tree (i.e. the name does not contain a '.' or an 'x-' prefix for historical reasons).
- zedr 14y ago
  Yes, it is compliant. In this example, the (version, 2) key/value pair is an accept-extension. http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html Another example of header field extensions could be `Content-Type: text/html; level=3`
dragonwriter 14y ago
> 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.

by zedr 14y ago

buro9 14y ago

That's OK, the title of the article says "RESTful" and not "REST". Pragmatically I've found through experience that most developers tend to be more comfortable thinking of URLs and general content types.

mnarayan01 14y ago

Accept: application/json; version=2 Is that a standard-compliant media type? `version` doesn't appear to be associated with application/json in the IANA media type registry, and I couldn't find anything definitive about adding arbitrary parameters.

masklinn 14y ago
I'm pretty sure parameters are not limited to those provided by IANA (just as media types are not necessarily IANA-registered incidentally) e.g. RFC2616's Accept doc shows a `level` parameter to text/html which is not IANA-specified (and seems entirely unspecified)
- mnarayan01 14y ago
  Yea I saw the use of level in the example but didn't think to look at the text/html spec to see if it was there. That would seem to imply that you are correct (though it would be nice if there were an explicit answer on this, if only for purely OCD reasons). > just as media types are not necessarily IANA-registered incidentally Per RFC4288 I believe they must be if they are in the standard tree (i.e. the name does not contain a '.' or an 'x-' prefix for historical reasons).
zedr 14y ago
Yes, it is compliant. In this example, the (version, 2) key/value pair is an accept-extension. http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html Another example of header field extensions could be `Content-Type: text/html; level=3`

dragonwriter 14y ago

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