Link Relation Types for Web Services
draft-wilde-service-link-rel-10

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.)

Please use the RFC 8174 boilerplate in lieu of the RFC 2119 boilerplate.

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.

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).

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.