3 ms·

Roy Fielding himself had an interesting interview [0] where versioning a REST API was one of the topics (spoilers: version is not in the url nor headers). [0]:

by hdhzy 9y ago

Roy Fielding himself had an interesting interview [0] where versioning a REST API was one of the topics (spoilers: version is not in the url nor headers). [0]: https://www.infoq.com/articles/roy-fielding-on-versioning/ https://www.infoq.com/articles/roy-fielding-on-versioning/

eriknstr 9y ago
> My point was that there is no need to anticipate such world-breaking changes with a version ID. We have the hostname for that. What you are creating is not a new version of the API, but a new system with a new brand. I think Rich Hickey (the creator of Clojure) would agree. He said something to this effect in the "Spec-ulation" keynote at Clojure/conj 2016. https://www.youtube.com/watch?v=oyLBGkS5ICk https://www.youtube.com/watch?v=oyLBGkS5ICk
deathanatos 9y ago
I'm going to have to disagree with him. If I need to break compatibility on a single resource, I don't want to mirror every API endpoint (except that one) to a new hostname. That becomes continually more and more complex and hard to keep sense of as changes progress. The hostname thing might work for huge, world-changing re-writes, but for small, incremental changes, I think something like what GitHub does w/ the Accept header is far more appropriate.
- prebrov 9y ago
  His argument is for API discoverability. Client should be able to learn about available endpoints [edit: ...and resources. And be able to comprehend resource record conventions]
  - deathanatos 9y ago
    I also don't see the point of API discoverability, at least, not programmatically. Sure, such a thing could be built, but I don't know what could be done w/ the results. Most API's I've ever worked on required domain knowledge in order to operate on (e.g., you had to understand the content — semantically — of the result. I.e., you needed to understand what a `applicaiton/vnd.bigcorp.widget.v2+json` was.) I just don't see any generic operations w.r.t. discovery that are … useful. I'm not trying to say that you shouldn't, e.g., use URLs in your resulting resources; e.g., if a query for a widget returns: { "widget_name": "NextGen Enterprise Widget", "suppliers": "http://bigcorp.example.com/widget/123/suppliers" } That's fine. But you're still going to need to know how to parse the result of …/suppliers, or it's just opaque bytes.

by hdhzy 9y ago

eriknstr 9y ago

> My point was that there is no need to anticipate such world-breaking changes with a version ID. We have the hostname for that. What you are creating is not a new version of the API, but a new system with a new brand. I think Rich Hickey (the creator of Clojure) would agree. He said something to this effect in the "Spec-ulation" keynote at Clojure/conj 2016. https://www.youtube.com/watch?v=oyLBGkS5ICk https://www.youtube.com/watch?v=oyLBGkS5ICk

deathanatos 9y ago

I'm going to have to disagree with him. If I need to break compatibility on a single resource, I don't want to mirror every API endpoint (except that one) to a new hostname. That becomes continually more and more complex and hard to keep sense of as changes progress. The hostname thing might work for huge, world-changing re-writes, but for small, incremental changes, I think something like what GitHub does w/ the Accept header is far more appropriate.

prebrov 9y ago
His argument is for API discoverability. Client should be able to learn about available endpoints [edit: ...and resources. And be able to comprehend resource record conventions]
- deathanatos 9y ago
  I also don't see the point of API discoverability, at least, not programmatically. Sure, such a thing could be built, but I don't know what could be done w/ the results. Most API's I've ever worked on required domain knowledge in order to operate on (e.g., you had to understand the content — semantically — of the result. I.e., you needed to understand what a `applicaiton/vnd.bigcorp.widget.v2+json` was.) I just don't see any generic operations w.r.t. discovery that are … useful. I'm not trying to say that you shouldn't, e.g., use URLs in your resulting resources; e.g., if a query for a widget returns: { "widget_name": "NextGen Enterprise Widget", "suppliers": "http://bigcorp.example.com/widget/123/suppliers" } That's fine. But you're still going to need to know how to parse the result of …/suppliers, or it's just opaque bytes.