Subject: Re: [weirds] help

From: "Murray S. Kucherawy" <[email-masked]>
Date: Tue, 21 May 2013 10:52:33 -0700

Hey all,

Where did we land with this "help" link relation suggestion?  There seemed
to be general support for the idea, but Andy requested proposed text and I
don't see that he got any.

-MSK

On Mon, Apr 15, 2013 at 10:39 AM, Andy Newton <[email-masked]> wrote:

>   From: Ernie Dainow <[email-masked]>
> Date: Monday, April 15, 2013 11:11 AM
> To: Andrew Newton <[email-masked]>
> Cc: "[email-masked]" <[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
>
> _______________________________________________
> weirds mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/weirds
>
>

---

From: Ernie Dainow <[email-masked]>
Date: Wed, 22 May 2013 12:00:41 -0400

My comment on April 12 was intended to provide some basic text. Perhaps
that got missed in the follow-up discussion about whether a standard url to
a help page should be standardized or whether it was sufficient to embed
help/about links in RDAP objects.

-Ernie

---

From: Andy Newton <[email-masked]>
Date: Thu, 23 May 2013 16:45:46 +0000

From: Ernie Dainow <[email-masked]<mailto:[email-masked]>>
Date: Wednesday, May 22, 2013 12:00 PM
To: "Murray S. Kucherawy" <[email-masked]<mailto:[email-masked]>>
Cc: Andrew Newton <[email-masked]<mailto:[email-masked]>>, "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Subject: Re: [weirds] help

My comment on April 12 was intended to provide some basic text. Perhaps that got missed in the follow-up discussion about whether a standard url to a help page should be standardized or whether it was sufficient to embed help/about links in RDAP objects.

I believe you are correct with how the thread has progressed.

To paraphrase John Levine, any client not dealing with the rdap+json media type is not an RDAP client. Therefore a /help path that does not return rdap+json is not focused on serving RDAP clients and is not RDAP (at least if you follow the logic).

I'm not against implementers having a /help that returns HTML or plain text, but that sounds more like a BCP rather than part of the RDAP standard.

-andy

---

From: Ernie Dainow <[email-masked]>
Date: Fri, 24 May 2013 10:54:34 -0400

So we could have a simple rdap/help query that returns rdap+json with 
help information. The issue is not whether the response is html, links 
or even a remarks array but rather a standard way for people to get the 
basic information they need to successfully use the service, especially 
when encountering the errors outlined earlier.

-Ernie

On 5/23/2013 12:45 PM, Andy Newton wrote:
> From: Ernie Dainow <[email-masked] <mailto:[email-masked]>>
> Cc: Andrew Newton <[email-masked] <mailto:[email-masked]>>, 
> "[email-masked] <mailto:[email-masked]>" <[email-masked] 
> <mailto:[email-masked]>>
>     My comment on April 12 was intended to provide some basic text.
>     Perhaps that got missed in the follow-up discussion about whether
>     a standard url to a help page should be standardized or whether it
>     was sufficient to embed help/about links in RDAP objects.
>
>
> To paraphrase John Levine, any client not dealing with the rdap+json 
> media type is not an RDAP client. Therefore a /help path that does not 
> return rdap+json is not focused on serving RDAP clients and is not 
> RDAP (at least if you follow the logic).
>
> I'm not against implementers having a /help that returns HTML or plain 
> text, but that sounds more like a BCP rather than part of the RDAP 
> standard.
>
> -andy

---

From: "John Levine" <[email-masked]>
Date: 24 May 2013 23:57:15 -0000

In article <[email-masked]> you write:
>-=-=-=-=-=-
>-=-=-=-=-=-

RDAP is intended to be fetched and parsed by machines.  I understand
that people help might want help info, but I don't see any advantage
of shoehorning it into RDAP.  What would the JSON contain that would
be useful to a machine?

Also, if we do our work properly, an RDAP client shouldn't need
anything beyond the base URL of an RDAP server to work, and that's the
boostrapping problem that we've deferred for now.

If clients have to do something customized for each server to get
useful results, RDAP will be pretty useless.

---

From: Ernie Dainow <[email-masked]>
Date: Mon, 27 May 2013 13:49:48 -0400

> useful results, RDAP will be pretty useless.

Take as a representative case an RDAP client built to display data on a 
web page. If the client encounters an authentication error, I doubt it 
will have the smarts or the knowledge to create a request for 
authentication credentials. This is information the end user will need.

Beyond the end user, consider the developer trying to write an RDAP 
client. If the server has documented limitations or optional parts of 
the spec that are not supported, the developer can build this into the 
client. Otherwise, the end user will likely encounter errors with say 
some TLDs and not others.

Without documentation, software is built with trial and error and rarely 
handles errors well. RDAP servers should make it easy for developers to 
get the information they need to build good clients.

Other information that should be in a help are:
- What objects the server supports and names of a few objects that exist 
so that a client (developer) can do some basic tests.
- Description of any extensions.
- 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.
- How to get technical support for problems.

-Ernie

---

From: "John R Levine" <[email-masked]>
Date: 27 May 2013 14:46:02 -0400

> Take as a representative case an RDAP client built to display data on a web 
> page. If the client encounters an authentication error, I doubt it will have 
> the smarts or the knowledge to create a request for authentication 
> credentials. This is information the end user will need.

As I think I said, I agree that help text might be useful.  But I still 
don't see any reason to encode it in JSON, as opposed to a conventional 
URL that returns a free form web page people can look at.

R's,
John

PS: Also, what kind of lame client wouldn't be able to tell that an 
autnentication error on an unauthenticated request means that it wants 
credentials?  HTTP authentication in browsers has dealt with this 
situation for approximately 20 years.

---

From: Andy Newton <[email-masked]>
Date: Wed, 29 May 2013 14:40:19 +0000

>URL that returns a free form web page people can look at.

John,

Can we compromise here? Can we have a standard /help path that returns a
JSON "notices" object that may also have links?

Personally I think this will be seldom used, but it isn't harmful either.

-andy

---

From: "John R Levine" <[email-masked]>
Date: 29 May 2013 11:39:47 -0400

> JSON "notices" object that may also have links?

I agree that a help path that nobody uses isn't likely to cause a lot of 
damage, but I'm getting the impression that Ernie and I have completely 
different models about what WEIRDS is for.  In particular, I expect the 
fraction of WEIRDS lookups that have a human user nearby who might ask for 
the help link to be within rounding error of zero.

The whole point (as I understand it) is to have a way to query for WHOIS 
data that works reliably for automated clients, so they don't have to do 
web page scraping, or try to pick bits out of free format port 43 queries. 
That's why I feel pretty strongly that if a query doesn't return JSON that 
the client can process, there's no point to having the query.

Hence, BCP to have a help page nearby for users and developers good, help 
page that returns unusable JSON bad.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
"I dropped the toothpaste", said Tom, crestfallenly.

---

From: Ernie Dainow <[email-masked]>
Date: Wed, 29 May 2013 16:37:14 -0400

On 5/29/2013 11:39 AM, John R Levine wrote:
> I agree that a help path that nobody uses isn't likely to cause a lot 
> of damage, but I'm getting the impression that Ernie and I have 
> completely different models about what WEIRDS is for.  In particular, 
> I expect the fraction of WEIRDS lookups that have a human user nearby 
> who might ask for the help link to be within rounding error of zero.
>
> The whole point (as I understand it) is to have a way to query for 
> WHOIS data that works reliably for automated clients, so they don't 
> have to do web page scraping, or try to pick bits out of free format 
> port 43 queries. That's why I feel pretty strongly that if a query 
> doesn't return JSON that the client can process, there's no point to 
> having the query.
>
> Hence, BCP to have a help page nearby for users and developers good, 
> help page that returns unusable JSON bad.
>
I don't think there is a difference in understanding of what WIERDS is 
for. But some people seem to expect that implementations will all just 
work automagically and there will be no inter-operable problems. I have 
yet to see software or a standard that has achieved these goals. When 
failures occur, help information is one place to start to investigate 
the problem.

I don't care if help information is in a BCP or in RDAP, as long as it 
is easily and universally available. We should try to avoid the current 
state of Whois, where it is really difficult to find help. It took me 
months to discover how to do wildcard searches and on which domains it 
was supported.

It seems that the easiest way to provide standard access to help 
information is via a defined RDAP query. If returning a link in JSON to 
a help query is bad, then why do we have links throughout the other 
structures?

A BCP that simply recommends a help page is insufficient unless it 
defines a common way that people can locate that page. If someone can 
draft a BCP that makes it clear how end users and developers will get 
information from all servers, that meets the goal.

-Ernie

---

From: "John R Levine" <[email-masked]>
Date: 29 May 2013 16:53:36 -0400

> I don't think there is a difference in understanding of what WIERDS is for. 
> But some people seem to expect that implementations will all just work 
> automagically and there will be no inter-operable problems. I have yet to see 
> software or a standard that has achieved these goals. When failures occur, 
> help information is one place to start to investigate the problem.

No disagreement there.

> It seems that the easiest way to provide standard access to help information 
> is via a defined RDAP query. If returning a link in JSON to a help query is 
> bad, then why do we have links throughout the other structures?

Because, for the umpteenth time, the other fields have defined semantics 
beyond "someone might want to look at this."

> A BCP that simply recommends a help page is insufficient unless it defines a 
> common way that people can locate that page. If someone can draft a BCP that 
> makes it clear how end users and developers will get information from all 
> servers, that meets the goal.

How about http://<hostname>/help where the hostname is the one for the 
RDAP server.

Regards,

---

From: Andy Newton <[email-masked]>
Date: Thu, 30 May 2013 11:09:40 +0000

On 5/29/13 4:53 PM, "John R Levine" <[email-masked]> wrote:
>>defines a 

Isn't this exactly the interaction we've already defined? If you ask for
HTML content at /help you may get HTML content. If you ask for RDAP
content at /help you should get RDAP content.

I think you two are in agreement.

-andy

---

From: Ernie Dainow <[email-masked]>
Date: Thu, 30 May 2013 11:28:41 -0400

> I think you two are in agreement.
Sounds good to me.

Do we really need a separate BCP document for this? Are there are other 
topics that might make it worth adding a new document?

A section on error handling could be useful. There was some discussion 
about distinguishing between the different causes of HTTP 404 by adding 
information in an RDAP Error Response Body. But it might be better just 
to have these examples in the response doc.

-Ernie

---

From: "John R Levine" <[email-masked]>
Date: 30 May 2013 11:40:48 -0400

> Sounds good to me.

Just out of perverse curiosity, could you give an example of the JSON that 
a /help would return, and what the client would do with it?

You can assume the client is not running in a browser, or a console 
window, or anything else with a person watching.

Regards,

---

From: Ernie Dainow <[email-masked]>
Date: Thu, 30 May 2013 13:03:00 -0400

On 5/30/2013 11:40 AM, John R Levine wrote:
>> Sounds good to me.
>
> Just out of perverse curiosity, could you give an example of the JSON 
> that a /help would return, and what the client would do with it?
>

Here's an example that contains a link to an html help page. An 
alternative is a remarks array that contains the help text.

    "links": [
       {
          "href": "http://...",
          "rel": "help",
          "value": "http://..."
       },
       {
          "href": "http://example.com/help",
          "rel": "self",
          "value": "http://example.com/help"
       }
    ],
    "notices": [
       {
          "description": [
             "Access is provided to ... "
          ],
          "title": "TERMS OF USE"
       }
    ],
    "rdapConformance": [
       "rdap_level_0"
    ]

An automated client won't get this unless it makes a specific request 
for it. It can be useful to an automated client to verify the release 
level of the server software before continuing. Many APIs have a simple 
version request for this purpose.

A client implementing a web RDAP display for end users could use this if 
the user requested help. If it is smart enough and the user encounters 
an authentication failure, it could pop up the help page, since one of 
the things the help should provide is information about authentication 
credentials.

A developer would copy/paste the help link into a browser to get 
information like release notes, test objects, access to technical support.

-Ernie

---

From: "John R Levine" <[email-masked]>
Date: 30 May 2013 14:47:51 -0400

Other than the version number, which I think we have handled somewhere 
else, it strikes me as an overcomplex way for someone to look at a well 
known URL, but it's not worth further argument.

The notices thing is an actively bad idea.  I can tell you from years of 
people trying to put no-spam notices in SMTP banners that notices 
presented to other computers are meaningless.

R's,
John

On Thu, 30 May 2013, Ernie Dainow wrote:

>> You can assume the client is not running in a browser, or a console window, 
>> or anything else with a person watching.
>> 
>> Regards,
> Here's an example that contains a link to an html help page. An alternative 
> is a remarks array that contains the help text.
>
>   "links": [
>      {
>         "href": "http://...",
>         "rel": "help",
>         "value": "http://..."
>      },
>      {
> An automated client won't get this unless it makes a specific request for it. 
> It can be useful to an automated client to verify the release level of the 
> server software before continuing. Many APIs have a simple version request 
> for this purpose.
>
> A client implementing a web RDAP display for end users could use this if the 
> user requested help. If it is smart enough and the user encounters an 
> authentication failure, it could pop up the help page, since one of the 
> things the help should provide is information about authentication 
> credentials.
>
> A developer would copy/paste the help link into a browser to get information 
> like release notes, test objects, access to technical support.
>
> -Ernie
>
>
>

Regards,

---

From: Ernie Dainow <[email-masked]>
Date: Thu, 30 May 2013 16:31:54 -0400

On 5/30/2013 2:47 PM, John R Levine wrote:
> else, it strikes me as an overcomplex way for someone to look at a 
> well known URL, but it's not worth further argument.
The version is a common structure that is supposed to appear in all high 
level objects.

It's not a well known url unless a standard for it is established and 
published, which is the whole point of this discussion.
>
> The notices thing is an actively bad idea.  I can tell you from years 
> of people trying to put no-spam notices in SMTP banners that notices 
Notices is another common structure that is supposed to appear in all 
top objects. It was defined a while ago in 
draft-ietf-weirds-json-response-01.

-Ernie