Subject: Re: [weirds] help

From: Ernie Dainow <[email-masked]>
Date: Fri, 12 Apr 2013 14:38:05 -0400

On 1/31/2013 11:35 AM, Andy Newton wrote:
> 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
>
>
A help link may be useful for providing detailed information about a 
particular object but not for providing overall help. Suppose a client 
uses a redirection service and successfully retrieves data for many DNS 
names, but hits an authentication failure with a particular name. The 
user now has the redirected url to the correct server, so they append 
"help" to the path and get the documentation, which should provide 
requirements and instructions for authentication.

To support this, a standard path segment for "help" should be added to 
the rdap-query spec. Here is some proposed wording.

An RDAP user, whether an end user or a developer of a client 
application, may need to know a number of technical details. The 
response to "help" should display in a browser and provide basic 
documentation that a user needs to successfully use the service. Note 
that in some cases, it may be more useful to provide detailed 
documentation for a particular object by using a link in that object 
rather than in the general help.

Following is some of the general information that should be provided.
- What objects the server supports, for example domains for what TLDs
- Description of any extensions - custom path segments and JSON values.
- Whether authentication is required or not and how to get 
authentication credentials.
- Which optional parts of the spec are not supported (for example, what 
Search options).
- What is the rate limiting policy, so that a client can set appropriate 
delays.
- Typical "Release Notes" that may cover limitations, fixes or version 
differences.
- Names of a few objects that exist, so that a client can do some basic 
tests.
- How to get technical support for problems or unanswered questions (for 
example, including a comment submission form on the Help page).

-Ernie

---

From: Andy Newton <[email-masked]>
Date: Sat, 13 Apr 2013 15:45:42 +0000

>the rdap-query spec. Here is some proposed wording.

This capability is already available using either the "help" or "about"
link relation in the "links" array which can go inside the "notices" array.

-andy

---

From: Ernie Dainow <[email-masked]>
Date: Mon, 15 Apr 2013 11:11:27 -0400

There are several cases where the user may not get a JSON response and so
does not receive the notices array or anything else. For example, after
HTTP Unauthorized or Not Found. A standard way to get help independently of
looking for a link somewhere in a JSON response makes things a lot easier.

-Ernie

---

From: Andy Newton <[email-masked]>
Date: Mon, 15 Apr 2013 17:39:44 +0000

From: Ernie Dainow <[email-masked]<mailto:[email-masked]>>
Date: Monday, April 15, 2013 11:11 AM
To: Andrew Newton <[email-masked]<mailto:[email-masked]>>
Cc: "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Subject: Re: [weirds] help

There are several cases where the user may not get a JSON response and so does not receive the notices array or anything else. For example, after HTTP Unauthorized or Not Found. A standard way to get help independently of looking for a link somewhere in a JSON response makes things a lot easier.

No matter the response code, it is always possible to return an HTTP body. And the errorCode object (Section 7) can have a links array, though I guess that should be given in an example or made more explicit.

-andy