3 ms·

Or no versioning. Create new endpoint URIs for new semantics. Use vocabulary-based (property-based) entities and never change word (property) semantics. Cont

Or no versioning. Create new endpoint URIs for new semantics. Use vocabulary-based (property-based) entities and never change word (property) semantics. Contrary to its unpopularity (or because of?), this “strategy”* is far far simpler to maintain and evolve than is “versioning”. *I say “strategy” because this is more commonsense: it’s how we do things in the real world anyway.

braindeath 7y ago
I think this is still versioning. You just end up versioning with the endpoint URI. Eg many names that end -2 or -3.
- wellpast 7y ago
  If the semantics change, why do you need a “-2”? If the semantics don’t change, why do you need a new URI. Keep in mind you don’t have to focus on the suffix or the last part of the path name when you are naming things by URI. Also, why is it versioning? You have two endpoints in use. One happened to exist before the other one. That’s an incidental property. And there are scenarios where you may deprecate the latter before the former. Thinking in “versions” is not an accurate/ergonomic mapping of the domain anyway; we’ve just been tricked into thinking that way because... anthropology something.
  - deleted 7y ago
    [deleted]
  - antonvs 7y ago
    > If the semantics change, why do you need a “-2”? Because the API may serve the same purpose as the original, with some modified semantics. > Also, why is it versioning? Because the API may serve the same purpose as the original, with some modified semantics. Sharing a common name with versioning helps identify the relationships between the versions. It also avoids polluting the API namespace with a set of different names for different versions of essentially the same operations. > Thinking in “versions” is not an accurate/ergonomic mapping of the domain anyway; we’ve just been tricked into thinking that way because... anthropology something. It feels to me like you're trying to hard to be contrarian, or perhaps you're dealing with some special case scenario where your strategy makes sense. You'd need to explain the argument in significantly more detail to have a chance of making it convincing.
    - wellpast 7y ago
      See the link to Rich Hickey’s talk in my other comment. It covers the issues pretty well. I’m not being contrarian, but I am expressing frustration with a common yet unnecessarily complicated approach to a general problem. But I stand by my statements, they’ve paid off tremendously in real world contexts.
chrisweekly 7y ago
Could you please give an example of these property-based entities, or link to an API that follows this approach? I think I understand your suggestion but want to be sure. New endpoints for new semantics seems rock-solid to me along same lines as content-addressable / immutable build artifacts which I endorse.
- wellpast 7y ago
  Rich Hickey explains a similar thinking in this talk https://youtu.be/oyLBGkS5ICk https://youtu.be/oyLBGkS5ICk but it’s more directed at code libraries. The same arguments apply. I 100% think this is the way to go for internal APIs. For public APIs I may change my opinion here for more sociological/political reasons. The rational/technical reasons all still remain.
  - chrisweekly 7y ago
    Thanks! Helpful link, and args simply / well-put. :)

braindeath 7y ago

I think this is still versioning. You just end up versioning with the endpoint URI. Eg many names that end -2 or -3.

wellpast 7y ago
If the semantics change, why do you need a “-2”? If the semantics don’t change, why do you need a new URI. Keep in mind you don’t have to focus on the suffix or the last part of the path name when you are naming things by URI. Also, why is it versioning? You have two endpoints in use. One happened to exist before the other one. That’s an incidental property. And there are scenarios where you may deprecate the latter before the former. Thinking in “versions” is not an accurate/ergonomic mapping of the domain anyway; we’ve just been tricked into thinking that way because... anthropology something.
- deleted 7y ago
  [deleted]
- antonvs 7y ago
  > If the semantics change, why do you need a “-2”? Because the API may serve the same purpose as the original, with some modified semantics. > Also, why is it versioning? Because the API may serve the same purpose as the original, with some modified semantics. Sharing a common name with versioning helps identify the relationships between the versions. It also avoids polluting the API namespace with a set of different names for different versions of essentially the same operations. > Thinking in “versions” is not an accurate/ergonomic mapping of the domain anyway; we’ve just been tricked into thinking that way because... anthropology something. It feels to me like you're trying to hard to be contrarian, or perhaps you're dealing with some special case scenario where your strategy makes sense. You'd need to explain the argument in significantly more detail to have a chance of making it convincing.
  - wellpast 7y ago
    See the link to Rich Hickey’s talk in my other comment. It covers the issues pretty well. I’m not being contrarian, but I am expressing frustration with a common yet unnecessarily complicated approach to a general problem. But I stand by my statements, they’ve paid off tremendously in real world contexts.

chrisweekly 7y ago

Could you please give an example of these property-based entities, or link to an API that follows this approach? I think I understand your suggestion but want to be sure. New endpoints for new semantics seems rock-solid to me along same lines as content-addressable / immutable build artifacts which I endorse.

wellpast 7y ago
Rich Hickey explains a similar thinking in this talk https://youtu.be/oyLBGkS5ICk https://youtu.be/oyLBGkS5ICk but it’s more directed at code libraries. The same arguments apply. I 100% think this is the way to go for internal APIs. For public APIs I may change my opinion here for more sociological/political reasons. The rational/technical reasons all still remain.
- chrisweekly 7y ago
  Thanks! Helpful link, and args simply / well-put. :)