On Tue, Aug 22, 2017 at 10:10 AM, John C Klensin <john-ietf@xxxxxxx> wrote:
--On Monday, August 21, 2017 19:02 +0200 Toerless Eckert
<tte@xxxxxxxxx> wrote:
> John,
>
> I did like to use a couple of those nice email functions driven
> by special headers. IMHO the main reason why those never
> catched on is the absence of easy ways for users to figure out
> how much their software (MTU/MUA) sucks.
>
> One thing IMHO that would help are mechanisms to provide users
> with an easy ability to learn what their software is claiming
> to support, and what's missing. User experience should be some
> web-page that explains this to the user in easy terms and
> ideally even suggests to create RFE emails to the vendors. The
> question would then be what standards APIs one would need to
> enable interested third parties to generate such web pages
> (including IETF).
>...
Interesting idea, but a very different discussion (hence the
change of subject lines). As you know, the IETF has tended to
avoid API specifications, largely because we have preferred
performance standards (i.e., "this is what you need to do and
support") to implementation ones ("this is the API, probably
expressed on code or pseudocode, all you need to do is call
it"). We've also tended to focus on what happens or is
transmitted on the wire between machines rather than how and
what things are dong or implemented before the bits leave a
source system or after they get to a destination one. In
addition, many people have argued strongly that we should,
insofar as possible, stay out of the UI business, in part
because the IETF, as a community, demonstrably has no skill in
the area.
As you say later, this sort of thing needs regular review. As we go up the stack, the difference between an API and a protocol quickly blurs and eventually vanishes.
Protogen is a tool I use to generate protocol specifications and reference code from a common schema. It is similar in concept to YANG except being designed to be used at a much higher level. Here is an example of a specification written using it:
The API for the client library and server dispatch methods is generated from the same schema that generated the documentation. So a protocol specification is an API.
This is not the case for most IETF specs, of course, not even application specs. The 'cost' of doing that is that many of the choices that protocol designers often make are fixed:
* Encoding, is JSON
* Discovery is SRV
* Presentation is HTTP
I believe that making these choices consistent improves the spec.
The API is not the same as the user experience of course. But the design of an application protocol is mostly a choice of
* Which information to store at the client vs the server
* The ways the information is to be indexed at the server