There are 7 comments (sorted by their types, and the section they are about).
question comments
substantive comments
Comment LC-3059
Commenter: Erik Wilde <dret@berkeley.edu> (archived message ) Context: Document as a whole
Status: open
proposal
pending
resolved_yes
resolved_no
resolved_partial
other
assigned to Nobody
Type: substantive
editorial
typo
question
general comment
undefined
Comment :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.
Related issues: (space separated ids)
WG Notes: We had long discussions by email about this subject: https://lists.w3.org/Archives/Public/public-dwbp-comments/2015Jul/0002.html and https://lists.w3.org/Archives/Public/public-dwbp-comments/2015Oct/0000.html. Annette's email: Partially addressed. We don’t talk about fragment identifiers. I suggest we add it. This relates to LC-3058 and LC-3051.
Resolution: (Please make sure the resolution is adapted for public consumption)
Comment LC-3057
Commenter: Erik Wilde <dret@berkeley.edu> (archived message ) Context: Best Practice 14: Provide data in multiple formats
Status: open
proposal
pending
resolved_yes
resolved_no
resolved_partial
other
assigned to Nobody
Type: substantive
editorial
typo
question
general comment
undefined
Comment :"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".
Related issues: (space separated ids)
WG Notes: A BP was created to address this comment: https://www.w3.org/TR/dwbp/#Conneg
Proposed Resolution: Use Best Practice 22: Serving data and resources with different formats (https://www.w3.org/TR/dwbp/#Conneg) to address this comment. (Please make sure the resolution is adapted for public consumption)
Comment LC-3058
Commenter: Erik Wilde <dret@berkeley.edu> (archived message ) Context: Best Practice 14: Provide data in multiple formats
Status: open
proposal
pending
resolved_yes
resolved_no
resolved_partial
other
assigned to Nobody
Type: substantive
editorial
typo
question
general comment
undefined
Comment :"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).
Related issues: (space separated ids)
WG Notes:
Resolution: (Please make sure the resolution is adapted for public consumption)
Comment LC-3060
Commenter: Erik Wilde <dret@berkeley.edu> (archived message ) Context: 9.11 Data Access (BP Follow Rest Principles when designing APIs and BP Maintain separate versions for a data API)
Status: open
proposal
pending
resolved_yes
resolved_no
resolved_partial
other
assigned to Nobody
Type: substantive
editorial
typo
question
general comment
undefined
Comment :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.
Related issues: (space separated ids)
WG Notes: Email from Annette - Addressed: We now have a BP “Avoid breaking changes to your API”
Proposed Resolution: Addressed: We now have a BP “Avoid breaking changes to your API” (Please make sure the resolution is adapted for public consumption)
Comment LC-3063
Commenter: Andreas Kuckartz <a.kuckartz@ping.de> (archived message ) Context: Best Practice 24: Follow REST principles when designing APIs
Status: open
proposal
pending
resolved_yes
resolved_no
resolved_partial
other
assigned to Nobody
Type: substantive
editorial
typo
question
general comment
undefined
Comment :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
>
>
>
Related issues: (space separated ids)
WG Notes: For this comment, it's important to notice the following discussion on the subject.
(http://lists.w3.org/Archives/Public/public-dwbp-wg/2015Jul/0037.html#replies)
Resolution: (Please make sure the resolution is adapted for public consumption)
editorial comments
Comment LC-3062
Commenter: Erik Wilde <dret@berkeley.edu> (archived message ) Context: Abstract
Status: open
proposal
pending
resolved_yes
resolved_no
resolved_partial
other
assigned to Nobody
Type: substantive
editorial
typo
question
general comment
undefined
Comment :(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
Related issues: (space separated ids)
WG Notes: A message was sent to Erik.
https://lists.w3.org/Archives/Public/public-dwbp-wg/2016Mar/0128.html
Proposed Resolution: To update the text on the DWBP document to replace public-dwbp-wg@w3.org by public-dwbp-comments@w3.org. (Please make sure the resolution is adapted for public consumption)
Add a comment .