Subject: Re: [Anima] Murray Kucherawy's No Objection on draft-ietf-anima-grasp-api-08: (with COMMENT)

From: Brian E Carpenter <[email-masked]>
Date: Wed, 2 Dec 2020 08:21:53 +1300

Murray,

Yes, in practice there's no such thing as a missing return value. Will clarify.

Thanks
   Brian

On 01-Dec-20 18:56, Murray Kucherawy via Datatracker wrote:
> Murray Kucherawy has entered the following ballot position for
> draft-ietf-anima-grasp-api-08: No Objection
> 
> When responding, please keep the subject line intact and reply to all
> email addresses included in the To and CC lines. (Feel free to cut this
> introductory paragraph, however.)
> 
> 
> Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
> for more information about IESG DISCUSS and COMMENT positions.
> 
> 
> The document, along with other ballot positions, can be found here:
> https://datatracker.ietf.org/doc/draft-ietf-anima-grasp-api/
> 
> 
> 
> ----------------------------------------------------------------------
> COMMENT:
> ----------------------------------------------------------------------
> 
> This might be an implementation detail, but I feel like bringing attention to
> it to clarify:
> 
> Looking at this as a guide to API implementers, I'm confused by one aspect to
> this document.  There are portions of the API specification where some of the
> returned items are conditional.  For example, in Section 2.3.3, the response to
> "register_asa()" always contains an "errorcode" but it will also contain an
> "asa_nonce" if registration was successful.  What does it mean for a response
> to be sometimes missing a piece of information?  I'm thinking, for instance,
> about python where your response might be a single value or a tuple of values
> depending on success or failure, and I as the consumer will have to handle each
> case separately.   Wouldn't it be simpler for "asa_nonce" to have a possible
> sentinel value for use in failures?  (Maybe 0, maybe -1, maybe MAXINT; the use
> of "integer" in the document generally doesn't specify whether it's signed or
> unsigned or what limits might exist.  Or maybe "None".) That way, responses
> always have the same number of elements and possibly types irrespective of the
> function's outcome.
> 
> For a more extreme example, the response to "request_negotiate()" could have
> anywhere between one and four elements in it too, and of varying types.
> 
> It's possible this doesn't matter though; you're doing the API implementation,
> you get to decide and document it and then deal with user response.  But as
> someone who produces and documents APIs a lot, this stuck out to me.
> 
> 
> 
>