4 ms·

good article but...he says version numbers in the url are bad but doesn't say why. using accept headers for versioning is a hassle for every client and makes br

good article but...he says version numbers in the url are bad but doesn't say why. using accept headers for versioning is a hassle for every client and makes browser based testing much more difficult. also a v1 user really might not be the same as a v2 user so they shouldn't be the same resource.

notJim 15y ago
You keep your practical considerations away from this man's ivory tower!
icebraining 15y ago
>he says version numbers in the url are bad but doesn't say why. Because according to the spec, each resource is named by a single URL, so two URLs name two different resources. But if you put version numbers in the URL, you might end up with http://example.org/v1/rubyrescue http://example.org/v1/rubyrescue and http://example.org/v2/rubyrescue http://example.org/v2/rubyrescue, which according to the spec are two different users but in reality they're the same. >also a v1 user really might not be the same as a v2 user In what cases should the users be tied to the API version? I can't think of any.
- rubyrescue 15y ago
  good point, but the point of a restful resource is that the url represents a resource, but then w/accept header versioning, i now need two pieces of data, one of which isn't visible, to properly represent and retrieve a resource. I guess my point is that if i have to pick, i'd rather occasionally have two request urls with a minor version difference that are actually the same resource than two urls that appear to be the same resource but are not because one was requested with a header that affects the returned data.
  - icebraining 15y ago
    You're confusing resource with representation. An URL is a resource, but if the representation of that is a JSON document or a picture of him/her, that's up to the server. Just because an header affects the representation of a resource, doesn't mean they're different resources.
    - rubyrescue 15y ago
      actually that's a good example that makes my point. if i said to you - well if you want to retrieve a person's user information, just GET /users/1 with Accept: text/json. If you want their photo, just GET /users/1 with Accept: image/jpeg - philosophically, i'm not violating the 'rules of REST' but it feels wrong to me.
      - icebraining 15y ago
        Sure, I would create a "User's photo" resource too and link it from /users/1, but that's because a user's photo can be a new resource, so it can have its own URL.
  - stanleydrew 15y ago
    What do you mean by visible? Visible in the URL bar of a browser? The headers are all there in the request, for all to see.
    - rubyrescue 15y ago
      yes i'm thinking more pragmatically. From an API perspective the header is part of the request but given that the human-readability of urls is a feature of http, it just somehow feels wrong to me to modify the response based on a request header.
      - glassx 15y ago
        I think most developers don't see that as a problem. We modify the response all the time based on headers like User-Agent, Referer, If-Unmodified-Since, Accept-Language and others, so using Accept for versioning isn't really that strange.
        Dylan16807 15y ago
        User-Agent: modifying based on this is a Bad Thing Referer, If-Unmodified-Since: these only decide if you respond or don't or error, they don't generally change a successful transfer Accept-Language: I was under the impression that this was buggy and not well-supported, but it is a good example in theory
        icebraining 15y ago
        The response is changed all the type depending on the value of the Cookie header.
- stanleydrew 15y ago
  "Because according to the spec, each resource is named by a single URL, so two URLs name two different resources." I don't think this is technically correct. For instance, you might have a blog with a post at /blog/2011/07/03/why-i-love-rest and you might have /blog/current represent the same resource until you post something new. This seems like a valid case in which two different URIs name the same resource. If you are versioning the resources themselves I think the version in the URI is perfectly fine. In reality this is almost never the case and people mainly use the version in the URI to designate different versions of the representation. This is bad since it ties the URI to the representation which is a big no-no.
  - icebraining 15y ago
    Hmm, I think that those URLs are still different resources; one is 'the current post' and the other is 'the post named "Why I love REST"'. I would do a 302 from the latter to the former.
    - stanleydrew 15y ago
      Ah, fair enough. They are indeed two different resources. Would you have a problem if I returned the actual representation rather than a 302?
      - icebraining 15y ago
        I don't have a 'problem' with it, this is just conceptual talk. But I'd still do it for SEO reasons. If Google fetched /blog/current as containing the "Why I love REST" post and showed it to me, and the when I clicked the link I got "Why I think turtles are awesome", I'd be annoyed. A 302 fixes that in a more clean way than entries in robots.txt or similar tricks. EDIT: Apparently Google messes that up and often associates the content with the source URL and not the destination URL. Disregard the previous paragraph.
        dedward 15y ago
        Seems like people are mixing up ways of providing web services with overall site design and url friendliness......
- dennyabraham 15y ago
  iiuc, two resources can contain the same value, (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_1 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...) so you're not constrained by the number of identifiers with which you can reference a single entity. furthermore, it's debatable whether the versioned identifier hierarchy adheres to the principles of HATEOAS and discoverability, so practicality probably rules when implementing such an API.

notJim 15y ago

You keep your practical considerations away from this man's ivory tower!

icebraining 15y ago

>he says version numbers in the url are bad but doesn't say why. Because according to the spec, each resource is named by a single URL, so two URLs name two different resources. But if you put version numbers in the URL, you might end up with http://example.org/v1/rubyrescue http://example.org/v1/rubyrescue and http://example.org/v2/rubyrescue http://example.org/v2/rubyrescue, which according to the spec are two different users but in reality they're the same. >also a v1 user really might not be the same as a v2 user In what cases should the users be tied to the API version? I can't think of any.

rubyrescue 15y ago
good point, but the point of a restful resource is that the url represents a resource, but then w/accept header versioning, i now need two pieces of data, one of which isn't visible, to properly represent and retrieve a resource. I guess my point is that if i have to pick, i'd rather occasionally have two request urls with a minor version difference that are actually the same resource than two urls that appear to be the same resource but are not because one was requested with a header that affects the returned data.
- icebraining 15y ago
  You're confusing resource with representation. An URL is a resource, but if the representation of that is a JSON document or a picture of him/her, that's up to the server. Just because an header affects the representation of a resource, doesn't mean they're different resources.
  - rubyrescue 15y ago
    actually that's a good example that makes my point. if i said to you - well if you want to retrieve a person's user information, just GET /users/1 with Accept: text/json. If you want their photo, just GET /users/1 with Accept: image/jpeg - philosophically, i'm not violating the 'rules of REST' but it feels wrong to me.
    - icebraining 15y ago
      Sure, I would create a "User's photo" resource too and link it from /users/1, but that's because a user's photo can be a new resource, so it can have its own URL.
- stanleydrew 15y ago
  What do you mean by visible? Visible in the URL bar of a browser? The headers are all there in the request, for all to see.
  - rubyrescue 15y ago
    yes i'm thinking more pragmatically. From an API perspective the header is part of the request but given that the human-readability of urls is a feature of http, it just somehow feels wrong to me to modify the response based on a request header.
    - glassx 15y ago
      I think most developers don't see that as a problem. We modify the response all the time based on headers like User-Agent, Referer, If-Unmodified-Since, Accept-Language and others, so using Accept for versioning isn't really that strange.
      - Dylan16807 15y ago
        User-Agent: modifying based on this is a Bad Thing Referer, If-Unmodified-Since: these only decide if you respond or don't or error, they don't generally change a successful transfer Accept-Language: I was under the impression that this was buggy and not well-supported, but it is a good example in theory
        icebraining 15y ago
        The response is changed all the type depending on the value of the Cookie header.
stanleydrew 15y ago
"Because according to the spec, each resource is named by a single URL, so two URLs name two different resources." I don't think this is technically correct. For instance, you might have a blog with a post at /blog/2011/07/03/why-i-love-rest and you might have /blog/current represent the same resource until you post something new. This seems like a valid case in which two different URIs name the same resource. If you are versioning the resources themselves I think the version in the URI is perfectly fine. In reality this is almost never the case and people mainly use the version in the URI to designate different versions of the representation. This is bad since it ties the URI to the representation which is a big no-no.
- icebraining 15y ago
  Hmm, I think that those URLs are still different resources; one is 'the current post' and the other is 'the post named "Why I love REST"'. I would do a 302 from the latter to the former.
  - stanleydrew 15y ago
    Ah, fair enough. They are indeed two different resources. Would you have a problem if I returned the actual representation rather than a 302?
    - icebraining 15y ago
      I don't have a 'problem' with it, this is just conceptual talk. But I'd still do it for SEO reasons. If Google fetched /blog/current as containing the "Why I love REST" post and showed it to me, and the when I clicked the link I got "Why I think turtles are awesome", I'd be annoyed. A 302 fixes that in a more clean way than entries in robots.txt or similar tricks. EDIT: Apparently Google messes that up and often associates the content with the source URL and not the destination URL. Disregard the previous paragraph.
      - dedward 15y ago
        Seems like people are mixing up ways of providing web services with overall site design and url friendliness......
dennyabraham 15y ago
iiuc, two resources can contain the same value, (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_1 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...) so you're not constrained by the number of identifiers with which you can reference a single entity. furthermore, it's debatable whether the versioned identifier hierarchy adheres to the principles of HATEOAS and discoverability, so practicality probably rules when implementing such an API.