Summary: Has enough positions to pass.
Why is this informational? It seems to be defining a standard. I see that the shepherd review says it has had insufficient review for the standards track. The reasoning should be reflected somewhere in the text of the document. (I agree with Mirja's comment that "experimental" might be the appropriate choice.) §2: I agree with comments to use the RFC 8174 boilerplate. But IDNits says there are no normative keywords used, so maybe the boilerplate should just be removed.
Please use the RFC 8174 boilerplate in lieu of the RFC 2119 boilerplate.
It would be helpful to me, if there was a reference for the "service" link relation type in this text: 3.3. Unified Documentation/Description If service providers use an approach where there is no distinction between service documentation (Section 3.1) and service description (Section 3.2), then they may not feel the need to use two separate links. In such a case, an alternative approach is to use the "service" link relation type, which has no indication of whether it links to documentation or description, and thus may be a better fit if no such differentiation is required. and, for extra credit, if "service" was qualified as 3.3. Unified Documentation/Description If service providers use an approach where there is no distinction between service documentation (Section 3.1) and service description (Section 3.2), then they may not feel the need to use two separate links. In such a case, an alternative approach is to use the "service" link relation type, which has no indication of whether it ^ 'existing "service" link relation type' or 'previously defined "service" link relation type', or really anything that would tell me not to bother looking through the document looking for the definition of "service" because it's already been defined ;-) links to documentation or description, and thus may be a better fit if no such differentiation is required.
Thank you for the discussion relating to my Discuss point (preserved below as "OLD DISCUSS"). It seems somewhat inherent in the nature of link relations that this specification cannot guarantee that an arbitrary client following a service-descr link relation will be able to mechanically process the returned resource, and thus that any machine-readability will be subject to the implementation overlap between client and server. (Accordingly, I am clearing my Discuss position, as there is no in-scope reliable means by which to alleviate the indicated topic.) That said, we may still have scope to lay out a path for a future that improves the chances of successful machine readability. For example, Section 3.2 (Describing Web Services) concludes by noting: [...] model. Other description languages for non-RPC approaches to services will use different structuring approaches, such as structuring service descriptions by URIs and/or URI patterns. Would it be appropriate to also include some text here along the lines of "Future specifications may define machine-readable formats for describing service APIs and similar functionality, such as an OpenAPI description. If new media types are allocated for these formats, the normal HTTP Accept and content-type mechanisms can serve to give automated parsers confidence that they are processing the correct data structure. Nonetheless, these mechanisms are not a guarantee, and clients MUST always be prepared to handle unexpected content-types and response contents." OLD DISCUSS I think we may need to have a discussion about when it's appropriate to provide resources intended for machine consumption without a machine-readable way of knowing how to consume those resources. (See comments on Sections 3.2, 3.3, 4.3, and 5.) I also have some reservations about the "status" relation, or perhaps just with the way it is described. Section 1 implies that it is supposed to be about the status of the service as a whole, as opposed to potentially being limited to just the resource returning the link relation. Since web services, while widespread, are not universal, I would be reluctant to use such a generic term in the namespace for a more specific use case. The actual registration in Section 6.4 is more vague, though, talking just about the status of "the context", which I suppose could apply even to resources that are not part of a web service. It's quite possible I'm in the rough on one or both of those, in which case I'll happily clear. OLD COMMENT I agree with the directorate reviewers that there is a lot of duplicated content here and it detracts fromthe reader's experience. If we do end up pushing this as Experimental, would we have room to narrow down the semantics and representation of the status resource at such time as it is moved to the standards-track? Section 1 In addition, while both documentation and descriptions may be provided as part of a Web service, there may be other information as well. Generally speaking, a Web service may have any metadata/ resources associated with it (with documentation/description just being two specific kinds of resource). If there is a way how all of these metadata/resources are represented, then it should be possible to discover such a resource of general Web service metadata. I'm having trouble unpacking this (but I'm sick and short on sleep, so maybe it's just me). Is "way how [...] are represented" intended to mean something like "a single resourse presenting a high-level description of how these resources are organized"? Section 3.2 I'm a little uneasy about promulgating a thing that is stated as being machine-readable but without a machine-readable way to know how the contents are supposed to be interpreted. Content-type seems a bit too coarse-grained to be usable for this purpose, for example. (But if we publish as Experimental this concern mostly goes away.) Section 3.3 Are we advocating for using the "service" link relation type with no documentation on what the semantics of that link relation are supposed to be? Section 4.3 Same comment as for Section 3.2, but now about the lack of a concrete mechanism for the "hints". Section 5 A resource that may or may not be intended for machine consumption is pretty hard for a machine to consume absent a concrete signal that this instance of the resource is in fact intended for machine consumption. Section 7 Are the consumers supposed to manually verify the documentation by trying the API endpoints, or talking to the site owner out of band, or something else? Or is the "behave accordingly" just supposed to be "prepared to handle errors"? (In which case maybe it's better to say that directly.)
These comments are mostly for the responsible AD: 1) From the shepherd write-up it sounds like this document should experimental and not informational ("it hasn't been widely reviewed or implemented enough to make it standards-track"). 2) Why was this document not processed in the httpbis wg. It seems to be fully in scope for httpbis and if there is a suitable wg, I think it is always more appropriate to take the wg track with last call and and respective reviews than an individual submission. If the httpbis wg does not support this doc, it maybe shouldn't be processed in the IETF at all (and could e.g. also be published with the ISE to have a stable reference).
Thanks to everyone who worked on this document. I have a handful of questions and comments. =========================================================================== I-D Nits reports: == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. --------------------------------------------------------------------------- §3.3: > In such a case, an alternative approach is to use the > "service" link relation type, which has no indication of whether it > links to documentation or description I was going to ask that the document cite RFC 5023 here, as a simple reading of this section led me to believe that *this* document was attempting to define a link relation called "service," and was confused when no such link relation appeared in the IANA section. The problem I came across was, when I went to look at the definition of the "service" link relation in RFC 5023 (the document indicated for "service" in https://www.iana.org/assignments/link-relations/link-relations.xhtml), I found that it isn't actually defined there. This situation isn't *this* document's problem, although the comment -- that this document should make it clear that the "service" link relation is not being defined by this document -- still applies. --------------------------------------------------------------------------- §4.1: > The "service-doc" link relation type is used to represent the fact > that a resource is part of a bigger set of resources... Is it necessarily part of a bigger set of resources? If so, what link relation would I use if I wanted to point to documentation for a relatively simple service that was implemented using a single endpoint? (The same comment applies to §4.2) --------------------------------------------------------------------------- §4.2 and §4.3: This text makes it pretty hard for the reader to understand the distinction being made between the "service-desc" and "service-meta" link relations. Would it be possible to include a very simple example of each? --------------------------------------------------------------------------- §5: > Such a link may not be available for > and from all resources provided by a Web service, but from key > resources such as a Web service's metadata resource and/or a > service's home resource [I-D.nottingham-json-home]. Given that the cited draft has been expired for nearly a year and a half and hasn't been adopted by a working group, are we sure that a citation to it makes sense? What is the chance that this document eventually gets published? (I ask this knowing Mark is copied on this review.)