Subject: [weirds] help

From: Ernie Dainow <[email-masked]>
Date: Wed, 30 Jan 2013 15:06:38 -0500

An RDAP user, whether an end user or a developer of a client application,
may have a number of questions about the service. If they have the RDAP
url, it would be nice to make it easy to find documentation for the service
to answer questions such as:

- What objects the server supports, for example domains for what TLDs
- Description of any custom names. While the specification suggests
using "meaningful"
names, self-documenting systems often need supplementary explanations for
the full context to be properly understood.
- Whether authentication is required or not and how to request
authentication credentials.
- What search options are supported.
- Typical "release notes" that may cover limitations, fixes or version
differences.

Without any standards direction, documentation may or may not be provided
and will likely be a url that requires prior knowledge or guessing. It
would be useful to specify a standard way to get documentation about a
service. I suggest a help (or about or readme) object be added to the RDAP
query/response specifications.

-Ernie

---

From: "John Levine" <[email-masked]>
Date: 30 Jan 2013 21:51:07 -0000

>It would be useful to specify a standard way to get documentation about a

I can read this in two ways:

A) something like a well known url of /README that returns a page of
documentation intended to be read by people, with no structure beyond
a suggestion that it would be nice if it were HTML that the usual
browsers could render.

B) service discovery, in which the the response is intended to be
interpreted by client software so it can configure itself.

Option A is a fine idea, at worst harmless.  Option B is a swamp,
leading to things like URL templates that we've already considered and
rejected.

R's,
John

---

From: Arturo Servin <[email-masked]>
Date: Wed, 30 Jan 2013 20:00:53 -0200

I would vote for 1.

/as

On 30/01/2013 19:51, John Levine wrote:
> _______________________________________________
> weirds mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/weirds
>

---

From: "Hollenbeck, Scott" <[email-masked]>
Date: Thu, 31 Jan 2013 12:04:12 +0000

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On
> Behalf Of John Levine
> Sent: Wednesday, January 30, 2013 4:51 PM
> To: [email-masked]
> Subject: Re: [weirds] help
> 

I mildly prefer /help to /readme. This seems like a good idea that can be added to the query and response drafts; I'll take it up with Andy. Thanks for the suggestion.

Scott

---

From: Andy Newton <[email-masked]>
Date: Thu, 31 Jan 2013 15:16:37 +0000

>interpreted by client software so it can configure itself.

I don't think either is necessary.

We already accommodate link relations as defined RFC 5988. The IANA
registry for link relations, found here
http://www.iana.org/assignments/link-relations/link-relations.xml ,
already lists "help" along with other relations which might also be
appropriate.

Therefore I think no new protocol scaffolding is required to meet this
need. However, we can update our draft to reflect an example of using the
link relationship for pointing to help.

-andy

---

From: Warren Kumari <[email-masked]>
Date: Thu, 31 Jan 2013 10:54:25 -0500

> link relationship for pointing to help.

And possibly a note that implementations SHOULD (or should) support "help"?

W

--
"Real children don't go hoppity-skip unless they are on drugs."

    -- Susan, the ultimate sensible governess (Terry Pratchett, Hogfather)

---

From: Andy Newton <[email-masked]>
Date: Thu, 31 Jan 2013 16:07:34 +0000

>And possibly a note that implementations SHOULD (or should) support

Wouldn't that be an inappropriate use of 2119 language? Not supporting a
help linkage won't break interoperability of RDAP. Suggesting a SHOULD
indicates that RDAP interoperability might be in question should a help
linkage not be offered.

-andy

---

From: Warren Kumari <[email-masked]>
Date: Thu, 31 Jan 2013 11:26:54 -0500

> indicates that RDAP interoperability might be in question should a help

Fine -- so a "should" or a "recommend" or a "pretty please do this"… 

I don't really care how, but encouraging implementations to support it would be good…

W

--
Life is a concentration camp.  You're stuck here and there's no way out and you can only rage impotently against your persecutors.
                -- Woody Allen

---

From: Andy Newton <[email-masked]>
Date: Thu, 31 Jan 2013 16:35:50 +0000

On 1/31/13 11:26 AM, "Warren Kumari" <[email-masked]> wrote:

>Fine -- so a "should" or a "recommend" or a "pretty please do this"Š
>
>I don't really care how, but encouraging implementations to support it
>would be goodŠ

That works for me. If somebody would be willing to flesh out an outline or
some points that implementers might want to put in this help, I would
imagine that would go a long way to providing the proper context for
implementers to understand why providing this information is such a good
idea.

-andy