5 ms·

For the record Roy Fielding is against using version numbers in URLs: https://www.infoq.com/articles/roy-fielding-on-versioning/ https://www.infoq.com/articles/

For the record Roy Fielding is against using version numbers in URLs: https://www.infoq.com/articles/roy-fielding-on-versioning/ https://www.infoq.com/articles/roy-fielding-on-versioning/

sitkack 8y ago
Roy Fielding isn't a deity. The version would be encoded in the 'Accepts' content type header. There is little distinction, one is in-band (in the path) and one is out-of-band (in the header), but the information is still represented.
- dordoka 8y ago
  He is not a deity, of course, he's "just" the one that invented REST. I guess what you mean is that he's not right about everything he says. Well, what he exactly says is that URLs should not include versioning, because URLs are the interfaces names and REST estates that interface names should not be versioned, as that implies a breaking change in the API. It's just the wrong place for versioning in the REST way. But he is not against versioning, as you say, you can use the Accept header. You could also use a custom header if you might, but the canonical way would be the Accept header.
  - sitkack 8y ago
    I believe that Roy is nerd sniping us, I capitulate. Ok, Roy was wrong, versions in the URL don't break things, they make them stronger. Naming is hard, we republish a semantically related by different artifact and change the name rather than the varying part? Use etags instead? Change the domain? I totally understand asking for the version (Accepts) during a GET request. If I agreed on that content-type in advance, if I haven't I need to communicate both the url and the content-type along with the version to the clients. We don't have a common container for (url,content,version), things are getting messy. In a package manager, what is the equivalent of a GET request with an accepts header? import foo.bar v1.2.3 import foo.baz v2.1.3 new_thing = ::v2:foo.baz.new_thing(1) old_thing = ::v1:foo.bar.old_thing(2) Joe Armstrong has a great post on modules and versioning http://lambda-the-ultimate.org/node/5079 http://lambda-the-ultimate.org/node/5079 I am strongly infavor of immutable code, I think we should be able to import all versions of a library, referenceable by commit hash.
    - dordoka 8y ago
      Interesting idea. I usually code with languages that have lib packaging and depencency management systems. Recently I have went back to code on linux C and I quite miss them now. We have pushed the version management to the dependency or build management tools, but it would be awesome to be able to add that meta in code and those tools could also automate the tasks. BTW, wouldn't it be import foo.bar in both? It would be more logical to keep the name of the lib, import it twice, but with different version metadata. Thanks for the link as well! I would love to see that experimented somewhere and see if it works.
  - deleted 8y ago
    [deleted]
- mstade 8y ago
  I don’t think you have this right. First, both the URL and the headers are in-band. Out-of-band would be you knowing that the version is v2.3.7, because you just know. In-band is anything in the request and response – headers and all – anything else is an assumption and as such out-of-band. Moreover, if I understand Roy’s argument correctly, he’s arguing against versioning URLs, because they are meant to be opaque identifiers that doesn’t convey any universal meaning. If you know the second segment of a URL path to be a version, it’s because you have out-of-band knowledge that it is, not because there’s anything in the request to say it is. If however you have a header that tells what version you wish then that is in-band information that allows you to negotiate the content appropriately with the server. It also means you don’t have to change URLs whenever you make a change to your API, breaking or not. Of course the server and client needs to understand this header (to my knowledge there’s Accept-Version header) and if it’s non-standard then it can be argued that it’s just as bad as versioned URLs. Perhaps, but unless you get very granular with your versions (and most don’t, let’s just be honest) your still at the mercy of what the server chooses to present you at any given time. In fact, REST gives you no guarantees about what you’ll receive at any given point – you may just as well be given a picture of a cat. REST says you should be able to gracefully deal with this. Most clients (that aren’t web browsers or curl) don’t.
  - sitkack 8y ago
    > I don’t think you have this right. That is probably true, I don't disagree with anything you are saying. To me the most in-band representation is everything passed in the URL with no user control over headers.
    - Whitestrake 8y ago
      Using "in-band" here doesn't really follow from a technical understanding of the term; the TCP connection is the channel, and anything sent over it (such as an entire HTTP request/response, including headers) is "in-band". Out-of-band would be a phone call, or perhaps an email - an entirely alternate method of communication. Transparency to a user (via the client, i.e. browser) isn't really relevant, from a communications standpoint, to whether or not data is considered "out-of-band". Given the subject (APIs), you're not likely to be browsing to these anyway.
- alien_at_work 8y ago
  Well, I think from Roy's point of view REST is only HATEOAS. So URL's are irrelevant; you can put version numbers in there if you want but no client should realize it. What you should be versioning is your media types (e.g. HTML4 vs HTML5).
phlakaton 8y ago
Specifically as it applies to REST, though, and HATEOAS. I don't think it has much bearing to package versioning in Go...
nostalgeek 8y ago
> For the record Roy Fielding is against using version numbers in URLs: https://www.infoq.com/articles/roy-fielding-on-versioning/ https://www.infoq.com/articles/roy-fielding-on-versioning/ If Roy Fielding wanted developers to fully grasp whatever he was talking about with REST, he should have written a normative spec, not a dissertation, he didn't.

For the record Roy Fielding is against using version numbers in URLs: https://www.infoq.com/articles/roy-fielding-on-versioning/ https://www.infoq.com/articles/roy-fielding-on-versioning/

sitkack 8y ago

Roy Fielding isn't a deity. The version would be encoded in the 'Accepts' content type header. There is little distinction, one is in-band (in the path) and one is out-of-band (in the header), but the information is still represented.

dordoka 8y ago
He is not a deity, of course, he's "just" the one that invented REST. I guess what you mean is that he's not right about everything he says. Well, what he exactly says is that URLs should not include versioning, because URLs are the interfaces names and REST estates that interface names should not be versioned, as that implies a breaking change in the API. It's just the wrong place for versioning in the REST way. But he is not against versioning, as you say, you can use the Accept header. You could also use a custom header if you might, but the canonical way would be the Accept header.
- sitkack 8y ago
  I believe that Roy is nerd sniping us, I capitulate. Ok, Roy was wrong, versions in the URL don't break things, they make them stronger. Naming is hard, we republish a semantically related by different artifact and change the name rather than the varying part? Use etags instead? Change the domain? I totally understand asking for the version (Accepts) during a GET request. If I agreed on that content-type in advance, if I haven't I need to communicate both the url and the content-type along with the version to the clients. We don't have a common container for (url,content,version), things are getting messy. In a package manager, what is the equivalent of a GET request with an accepts header? import foo.bar v1.2.3 import foo.baz v2.1.3 new_thing = ::v2:foo.baz.new_thing(1) old_thing = ::v1:foo.bar.old_thing(2) Joe Armstrong has a great post on modules and versioning http://lambda-the-ultimate.org/node/5079 http://lambda-the-ultimate.org/node/5079 I am strongly infavor of immutable code, I think we should be able to import all versions of a library, referenceable by commit hash.
  - dordoka 8y ago
    Interesting idea. I usually code with languages that have lib packaging and depencency management systems. Recently I have went back to code on linux C and I quite miss them now. We have pushed the version management to the dependency or build management tools, but it would be awesome to be able to add that meta in code and those tools could also automate the tasks. BTW, wouldn't it be import foo.bar in both? It would be more logical to keep the name of the lib, import it twice, but with different version metadata. Thanks for the link as well! I would love to see that experimented somewhere and see if it works.
- deleted 8y ago
  [deleted]
mstade 8y ago
I don’t think you have this right. First, both the URL and the headers are in-band. Out-of-band would be you knowing that the version is v2.3.7, because you just know. In-band is anything in the request and response – headers and all – anything else is an assumption and as such out-of-band. Moreover, if I understand Roy’s argument correctly, he’s arguing against versioning URLs, because they are meant to be opaque identifiers that doesn’t convey any universal meaning. If you know the second segment of a URL path to be a version, it’s because you have out-of-band knowledge that it is, not because there’s anything in the request to say it is. If however you have a header that tells what version you wish then that is in-band information that allows you to negotiate the content appropriately with the server. It also means you don’t have to change URLs whenever you make a change to your API, breaking or not. Of course the server and client needs to understand this header (to my knowledge there’s Accept-Version header) and if it’s non-standard then it can be argued that it’s just as bad as versioned URLs. Perhaps, but unless you get very granular with your versions (and most don’t, let’s just be honest) your still at the mercy of what the server chooses to present you at any given time. In fact, REST gives you no guarantees about what you’ll receive at any given point – you may just as well be given a picture of a cat. REST says you should be able to gracefully deal with this. Most clients (that aren’t web browsers or curl) don’t.
- sitkack 8y ago
  > I don’t think you have this right. That is probably true, I don't disagree with anything you are saying. To me the most in-band representation is everything passed in the URL with no user control over headers.
  - Whitestrake 8y ago
    Using "in-band" here doesn't really follow from a technical understanding of the term; the TCP connection is the channel, and anything sent over it (such as an entire HTTP request/response, including headers) is "in-band". Out-of-band would be a phone call, or perhaps an email - an entirely alternate method of communication. Transparency to a user (via the client, i.e. browser) isn't really relevant, from a communications standpoint, to whether or not data is considered "out-of-band". Given the subject (APIs), you're not likely to be browsing to these anyway.
alien_at_work 8y ago
Well, I think from Roy's point of view REST is only HATEOAS. So URL's are irrelevant; you can put version numbers in there if you want but no client should realize it. What you should be versioning is your media types (e.g. HTML4 vs HTML5).

phlakaton 8y ago

Specifically as it applies to REST, though, and HATEOAS. I don't think it has much bearing to package versioning in Go...

nostalgeek 8y ago

> For the record Roy Fielding is against using version numbers in URLs: https://www.infoq.com/articles/roy-fielding-on-versioning/ https://www.infoq.com/articles/roy-fielding-on-versioning/ If Roy Fielding wanted developers to fully grasp whatever he was talking about with REST, he should have written a normative spec, not a dissertation, he didn't.