Subject: Re: IETF and APIs

From: "Randy Presuhn" <[email-masked]>
Date: Mon, 4 Apr 2011 11:03:14 -0700

Hi -

> From: "Tom Yu" <[email-masked]>
> To: "Sam Hartman" <[email-masked]>
> Cc: <[email-masked]>; <[email-masked]>
> Sent: Wednesday, March 30, 2011 2:40 PM
> Subject: Re: IETF and APIs
>
> Personal observation: "API" is a subclass of "interface".  "Network
> protocol" is a subclass of "interface".  Interfaces (in the general
> case) are valuable things to standardize.  An abstract interface
> ("abstract API"?) that gives guidance to implementors above and beyond
> the bare specification of the network protocol is useful for achieving
> conceptual alignment.
> 
> Do people agree?

Yes and no.  The experience with SNMPv3's ASIs (Abstract Service
Interfaces) might be instructive.

   (1) because implementations of the protocol (or something very
         similar to it) already existed, requiring conformance to the
         ASIs (beyond the externally-visible behaviour they described)
         found no support.

   (2) Despite (1), there are *still* people who think the ASIs will be reflected
         in implementations' APIs.  (They generally aren't.)

   (3) Even though there was already considerable experience with the
         implementation of the protocol when these Abstract Service
         Interfaces were defined, later work (especially in the isms WG)
         found that these definitions required some serious tweaks to
         handle cases that people were already thinking about when the
         interfaces were defined in the first place.

   (4) Some of the lengthy WG discussions and awkward hacks 
         resulting from (3) in subsequent RFCs  were only an artifact of
         the specification technique, and were not necessitated by
         actual protocol or implementation constraints, in my opinion.

Still, I think it can be very helpful to specify a C library API for things that are
actually intended to be used like libraries, but I also know that it can
be surprisingly difficult to get them "right" for all environments.

Randy

---

From: Eliot Lear <[email-masked]>
Date: Tue, 05 Apr 2011 09:02:11 +0200

Bob, Joe,

Given this viewpoint, what guidance would you give, then, to protocol
designers who are writing specifications?

Eliot

On 3/30/11 8:09 PM, Bob Braden wrote:
> +1
>
> Bpb Braden
>
> On 3/30/2011 1:11 AM, Joe Touch wrote:
>> Hi, all,
>>
>> Perhaps we're not talking about an API, or even an abstract API, but
>> just the "application interface" (or just "upper layer service"
>> specification).
>>
>> RFC793 is a great example that a protocol provides a service, and
>> that service needs to be explained - and that explaining it does NOT
>> need to be done in a specific language.
>>
>> Joe
>> _______________________________________________
>> Ietf mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/listinfo/ietf
>
> _______________________________________________
> Ietf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf
>

---

From: Joe Touch <[email-masked]>
Date: Tue, 05 Apr 2011 10:21:00 -0700

> designers who are writing specifications?

IMO, we have never really explained what we expect in a protocol 
specification. We focus on required sections like "security 
considerations" and "IANA considerations", but we've never explained 
what we're looking for in a protocol spec.

Here's what I expect:

- description/format of "on the wire" messages
	basically the I/O to the layer below

- state at the endpoints
	if any (it's rare that there is none, even for so-called
	'stateless' protocols), and whether it's hard or soft

- upper layer service
	the I/O to the layer above

- event and action table
	a list of events:
		- message arrival
		- upper layer service request
		- timer event
		- other event (queue overload, etc.; any other
		condition that can act as a trigger)

	for each event, in each state:
		list the actions
			e.g., messages to emit,
			upper layer responses/signals
			timers to set/reset
			other state (e.g., queues) to manage
		and whether the state changes

Overall, this is basically a Mealy machine description. That's what I 
expect, and why it includes the upper layer service, IMO.

If this sort of thing is useful, I'd be glad to write it up - and keep 
it short. I still expect that protocol designers are familiar with the 
basics of protocols. ;-)

Joe