search

HydraCG / Specifications

Specifications created by the Hydra W3C Community Group
Other
138 stars 26 forks source link

Discuss versioning #72

Closed lanthaler closed 5 years ago

lanthaler commented 9 years ago

In many cases, versioning is unavoidable in "traditional" HTTP-based Web APIs. Hypermedia APIs on the other hand should not need to rely on versioning and employ different strategies to ensure their evolvability. The Hydra Core Vocabulary specification should discuss this.

This issue was triggered by an interesting discussion on the mailing list:

On 19 Sep 2014 at 10:39, McBennett, Pat wrote:

Ruben Verborgh wrote on 19 Sep 2014 at 08:14:

On 19 Sep 2014 at 01:29, László Lajos Jánszky wrote:

1.) API versioning

Afaik by non backward compatible changes it is better to add a new API root with the major version number. What about the minor, revision and build numbers?

I'm not sure whether we need this. The use of hypermedia as the engine of application state should actually avoid the need for versioning in the majority of cases, just like you as a human can also navigate new versions of a site.

Very interesting point Ruben. It's this very 'dynamic-ness' of Hydra that sets it apart I think, but it also tends to confuse newcomers (since it's so unfamiliar to developers used to code- generating directly from static API descriptions like IDL or WSDL).

So should the spec somehow allude to the point that the concept of versioning needs to be reconsidered when using hypermedia (since developers (or at least the good ones!) will naturally ask 'how does API versioning work with Hydra?')...?

akuckartz commented 9 years ago

@lanthaler Is there a "not" missing in front of "need to rely on"?

Hypermedia APIs on the other hand should need to rely on versioning and employ different strategies

I compiled two somehow relevant links to material by Roy T. Fielding: https://github.com/OpenGovLD/specs/issues/84#issuecomment-68521192

lanthaler commented 9 years ago

Good catch. I added the “not”.

asbjornu commented 8 years ago

Any direction on where guidance on versioning should be mentioned? I guess it should be in an informative section of the specification, as there's nothing that affects an implementation of Hydra that should concern itself with versioning?

alien-mcl commented 5 years ago

Closed with PR #179