This document:Public document·View comments·Disposition of Comments·
Nearby:Data on the Web Best Practices Working Group Other specs in this tool
Quick access to LC-3057 LC-3058 LC-3059 LC-3060 LC-3061 LC-3062 LC-3063
Previous: LC-3060 Next: LC-3062
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 > > >