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

[Murray Kucherawy via Datatracker <[e-mail]>]

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.