- From: Tim Cole via GitHub <sysbot+gh@w3.org>
- Date: Thu, 30 Jun 2016 14:48:47 +0000
- To: public-annotation@w3.org
To summarize more fully: > "This specification is effectively profiling HTTP by using language like "The server must support > the following HTTP methods on the Annotation Container's URI." It should just describe the representations > and interaction expectations upon resources that use them."" We have reduced and clarified this as much as possible, following the patterns established by the Linked Data Platform specification which we build upon. For example, instead of saying that servers MUST support some HTTP interaction pattern, we say that If the server wishes to provide a particular feature, then it MUST allow it in a particular way. This results, we believe, in better interoperability without creating a profile of HTTP. We do not say, for example, that you MUST NOT allow the use of PUT to create an Annotation, but we do say that the server MUST implement POST as a means of creating Annotations, if that is a feature it wishes to support. We focus on the requirements that servers and clients need to rely on for interoperability within the domain of Annotations such that implementers have a recipe to follow, rather than expecting them to read every other specification and try to deduce all of the necessary features for themselves. > "Likewise, it's very MUST/SHOULD heavy; when specs overuse the RFC2119 terms, it doesn't help > readability or interoperability." We have tried to reduce the number of requirements, while still providing a sufficiently documented set of interactions to cover the use cases established. Whether there are too many requirements is very subjective -- if there were none, there would be nothing to conform to. We feel that since the version that Mark was likely reading ([2]), we have done a good job of reducing the protocol to its essential components plus those features that developers have asked for further clarity on. > "When a paging preference is received, instead of returning the representation of the > container, the server must return a response with the status code of 303 and a > Location header with the URI for the first page." What if the user isn't authorised? What if other > parts of the request are malformed? What if the resource doesn't exist? MUSTs like this are seldom helpful." The specification has been clarified regarding the success of any operation. The requirements now follow the pattern of "If the intended request is able to be successfully processed, then the server MUST/SHOULD ..." We agree with Mark that unconditional MUSTs are not helpful, as when things go wrong, an implementation cannot follow them. > "Error Conditions creates application-specific semantics for standard HTTP status codes. This is an > anti-pattern; the point of HTTP status codes is that any application (including intermediaries) can > understand them; application-specific semantics belong in the payload." We have clarified in response to this comment that the section on errors (now section 6) is informative, and the situations are examples of when those status codes might be appropriate to use. We believe that all of those examples are accurate according to the HTTP specification, and hence we are not overloading them with additional application specific semantics. -- GitHub Notification of comment by tcole3 Please view or discuss this issue at https://github.com/w3c/web-annotation/issues/313#issuecomment-229681515 using your GitHub account
Received on Thursday, 30 June 2016 14:49:06 UTC