This document:Public document·View comments·Disposition of Comments·
Nearby:Data on the Web Best Practices Working Group Other specs in this tool
Status: allopen proposal pending resolved_yes resolved_no resolved_partial other Type: allsubstantive editorial typo question general comment undefined
Quick access to LC-3057 LC-3058 LC-3059 LC-3060 LC-3061 LC-3062 LC-3063
There are 7 comments (sorted by their types, and the section they are about).
regarding best practice 30, i am wondering if https://github.com/dret/I-D/blob/master/sunset-header/draft-wilde-sunset-header-00.txt is something that might be worth mentioning in some form. this is currently a pre-I-D draft, but maybe the general idea of communicating resource availability is relevant for DWBP?
generally speaking, i am wondering why the terms hypertext or hypermedia are not even mentioned in the spec. isn't that what data on the web ideally should be, linkable and linked? https://github.com/dret/webdata#one-star-linkable and https://github.com/dret/webdata#four-star-linked are core principles for good web data. *linkable* means more than just URIs. it also means, for example, to provide meaningful and robust fragment identifiers for others to link to. *linked* means to use URIs and to specifically avoid other kinds of (often non-globally scoped) identifiers, so that links don't break when taken out of context.
"Best Practice 14: Provide data in multiple formats" might want to say if that should be done by different URIs, or one URI and HTTP conneg. that's a very typical question publishers have, so it should be mentioned at the very least, even if the answer is "we have no specific recommendation either way".
"Best Practice 14: Provide data in multiple formats" should say that for fragment identifiers to be consistent across formats, care is needed to make sure that this is the case (as much as possible, depending on the formats and their features).
best practices 24 and 27 kind of conflict. one important idea of REST is to avoid versioning, and having versioned URIs is a pretty certain sign of bad design smell when it comes to media types and API design.
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 > > >
(regarding the reply from Annette pointing out about the mailing list for comments.) thanks a lot for pointing this out, and in that case, comment number one for the current WD is to change the text in the spec that says: "If you wish to make comments regarding this document, please send them to public-dwbp-wg@w3.org. All comments are welcome." more comments in a separate email just to public-dwbp-comments@w3.org
Add a comment.