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

On Jul 27, 2015, at 00:53, Annette Greiner <amgreiner@lbl.gov> wrote:
> 
> Does anybody have an example of a successful HATEOAS compliant API that does not use versioning?

Sorry to keep repeating myself.  But, I'm thinking that Memento (which is all about versioning) is a most beautiful example of an HATEOAS "API". Only it's not an API, it's actually a protocol, the result of 4 years of interacting with communities, that is a totally straightforward extension of HTTP.  Memento as a protocol has no versions so far (so I think that meets your requirement). But it does provide uniform access to resources versions irrespective of whether those are version in web archives, wikis, versions of API descriptions,  versions of vocabularies, ontologies, etc. 

Regarding success: Memento has meanwhile been adopted by all major public web archives in the world. There's tools to support adoption by wikis, software versioning systems, etc but those seem to be more interested in exposing their proprietary API to access resource versions. And to expose their API versions.  Both could be handled using Memento. Would be nice if someone could convince them to look at Memento.

Cheers

Herbert

> 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
> 
>

Received on Wednesday, 29 July 2015 02:44:15 UTC