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. _______________________________________________ Anima mailing list [email protected] https://www.ietf.org/mailman/listinfo/anima
