Re: [dwbp] BP - URI structure is not relevant for REST

Just to add my 2 cents, not to have any confusion in the discussion, it
might be good to make it clear whether we are talking about versioned APIs
or versioned API URIs. IMO, what most people are against is versioned URIs
(which are also discouraged in the DWBP document).
*"If the data is made available through an API, the URI used to request the
latest version of the data should not change as the versions change, but it
should be possible to request a specific version through the API."* [1]

IMHO, versioning an API using media types (e.g.,
application/vnd.github.v3+json) as Github [2] has no incompatibility with
the REST principles.

Best Regards,
Nandana

[1] http://www.w3.org/TR/2015/WD-dwbp-20150625/#VersioningInfo
[2] https://developer.github.com/v3/

On Mon, Jul 27, 2015 at 8:53 AM, Annette Greiner <amgreiner@lbl.gov> wrote:

> Does anybody have an example of a successful HATEOAS compliant API that
> does not use versioning?
> I'm honestly wondering, not trolling here. In order to argue for something
> as a best practice, it helps to be able to point to successful use.
> -Annette
>
> On Jul 24, 2015, at 6:58 AM, Andreas Kuckartz <a.kuckartz@ping.de> wrote:
>
> > Unfortunately neither my mail from 2015-02-01 nor the brief discussion
> > about it in February 2015 seems to have had an effect on the BP document.
> >
> > As stated then I strongly disagree with the content of "Best Practice
> > 24: Follow REST principles when designing APIs".
> >
> > I can offer to provide a more concrete proposal for the content and to
> > contact Roy T. Fielding to ask him for feedback. But I need some kind of
> > guarantee that the result then finally will be considered by the WG.
> >
> > Cheers,
> > Andreas
> >
> >
> > Andreas Kuckartz wrote on 2015-02-01:
> >> Unfortunately the issue and the comments were deleted together with the
> >> Github issue tracker.
> >>
> >> Therefore let me repeat and extend my issue(s) here.
> >>
> >> Best Practice 23 has the title "Follow REST principles when designing
> >> APIs". One therefore expects that the following "principles" are REST
> >> principles and not other suggestions for APIs.
> >>
> >> I would suggest that JSON-LD is mentioned as a major hypermedia format.
> >> JSON-LD has already become far more important than XML for the Web.
> >>
> >> I would not mention UDDI. It which does not belong to REST and has
> >> become almost irrelevant years ago anyway.
> >>
> >> Why not refer to a relevant publicly available text written by Roy T.
> >> Fielding instead of the book by Richardson and Ruby which is not ?
> >>
> >> "Design always RESTful APIs using HTTP and good pragmatic REST
> >> principles.": What are "good pragmatic" REST principles?! I suggest to
> >> remove both "good" and "pragmatic".
> >>
> >> "There is no unique agreed set of principles for REST APIs, ..."
> >> "... others ... even are still under discussion."
> >>
> >> I disagree. There exist companies and people who either did not and do
> >> not bother to understand REST or who who just try to use the good name
> >> of REST to market non-RESTful APIs (often both at the same time). See:
> >> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
> >>
> >> "The following are a set of rules widely adopted so far: ..."
> >>
> >> A normal reader will then expect the rules or principles for RESTful
> >> APIs and not general suggestions for APIs. But the following "rules"
> >> have nothing at all to do with REST (which does *not* bother how URIs
> >> look like), they are orthogonal to REST:
> >>
> >> "Use hierarchical, readable and technology agnostic Uniform Resource
> >> Identifiers (URIs) to address resources in a consisten way."
> >>
> >> "Use the URI path to convey your Resources and Collections model."
> >>
> >> "Use nouns but no verbs (except for Controllers that does not involve
> >> resources)." (?What does that mean?)
> >>
> >> "Simplify associations. Use query parameters to hide complexity and
> >> provide filtering, sorting, field selection and paging for collections."
> >>
> >> And then finally there is this rule:
> >>
> >> "Version your API. Never release an API without a version and make the
> >> version mandatory."
> >>
> >> The last one is essentially in contradiction to REST. A good(!) RESTful
> >> API does require versioning.
> >>
> >> Cheers,
> >> Andreas
> >>
> >>
> >> Carlos Iglesias wrote:
> >>> Thanks Newton, I have followed the thread on github with my view on
> this.
> >>> Please Yaso feel free also to add any comments.
> >>>
> >>> On 21 January 2015 at 14:46, Newton Calegari <newton@nic.br
> >>> <mailto:newton@nic.br>> wrote:
> >>>
> >>>    Hi,
> >>>
> >>>
> >>>    There is an open issue [1] on Github related to a BP about REST.
> >>>
> >>>    Andreas Kuckartz, a github user, has commented on Carlos Iglesias’
> >>>    commit [2].
> >>>
> >>>    And he also created the Issue #80 [1] suggesting to review the BP
> >>>    "Follow REST principles when designing APIs" [3].
> >>>
> >>>    @Carlos Iglesias, @Yaso, I kindly as you to take a look on this
> >>>    issue and check if you agree or not with it.
> >>>
> >>>    Thanks,
> >>>    Newton
> >>>
> >>>    [1] https://github.com/w3c/dwbp/issues/80
> >>>
> >>>    [2]
> https://github.com/carlosiglesias/dwbp/commit/bdec0b8426e687d6615b789b17f48ddc5222fb93
> >>>    [3] http://w3c.github.io/dwbp/bp.html#BulkAccess2
> >>>
> >>>
> >>>
> >>>
> >>> --
> >>> ---
> >>>
> >>> Carlos Iglesias.
> >>> Internet & Web Consultant.
> >>> +34 687 917 759
> >>> contact@carlosiglesias.es <mailto:contact@carlosiglesias.es>
> >>> @carlosiglesias
> >>> http://es.linkedin.com/in/carlosiglesiasmoro/en
> >>
> >>
> >>
> >
>
>
>