Subject: Re: [Rum] Robert Wilton's Discuss on draft-ietf-rum-rue-09: (with DISCUSS and COMMENT)

From: Brian Rosen <[email-masked]>
Date: Thu, 20 Jan 2022 09:54:33 -0500

Rob

I submitted a -10 which I hope is satisfactory to you.

Brian

> On Dec 23, 2021, at 4:16 PM, Brian Rosen <[email-masked]> wrote:
> 
> Thank you for your comments.  Please see inline
> 
>> On Dec 15, 2021, at 7:37 AM, Robert Wilton via Datatracker <[email-masked]> wrote:
>> 
>> Robert Wilton has entered the following ballot position for
>> draft-ietf-rum-rue-09: Discuss
>> 
>> 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/blog/handling-iesg-ballot-positions/
>> for more information about how to handle DISCUSS and COMMENT positions.
>> 
>> 
>> The document, along with other ballot positions, can be found here:
>> https://datatracker.ietf.org/doc/draft-ietf-rum-rue/
>> 
>> 
>> 
>> ----------------------------------------------------------------------
>> DISCUSS:
>> ----------------------------------------------------------------------
>> 
>> There are a couple of points related to versioning that I would like to see
>> clarified, but I hope that it should be fairly easy to do so.
>> 
>> 1.
>>  This means an implementation of a
>>  specific major version and minor version is backwards compatible with
>>  all minor versions of the major version.
>> 
>> Is it actually compatible with all other minor versions, or only other minor
>> versions with a greater minor version number.  E.g., could an implementation be
>> coded to use/expect a object added in a minor version but that is not present
>> in preceding minor versions?
> All other minor versions.  
> 
> It has to be truly optional.  You can do things like add two parameters, a and b, and say if a is provided b must be provided, but it has to work if neither are there, and even if an implementation provided a but not b, an earlier version would ignore a.
> 
>> 
>> 2.
>>  The configuration API also provides the same version mechanism as
>>  specified above in Section 9.1.  The version of the configuration
>>  service MAY be different than the version of the provider list
>>  service.
>> 
>> It wasn't obvious to me, that for a given provider, how this is communicated. 
>> I'm not that familiar with OpenAPI, but looks like the /Versions path is a top
>> level API path, and the data that is contains seems to just be version numbers.
>> Hence, how would a client know which versions apply to provider list service
>> and/or which versions apply to the provide configuration service.
> ‘
> First of all, the Provider list is not available at alll providers.  It’s only available at a service that is one per country.  So one entity normally doesn’t supply both the Provider and the ProviderConfig entry points.
> To be really pedantic, I suppose that it’s actually possible for it to be one entity, and then that statement that there are separate versions wouldn’t apply.  So I guess I will change the text to:
> Unless the per-country provider list service is operated by a provider at the same base URI as that provider’s configuration service, the version of the configuration service MAY be different from the version of the provider list service.
> 
>> 
>> ----------------------------------------------------------------------
>> COMMENT:
>> ----------------------------------------------------------------------
>> 
>> Hi Brian,
>> 
>> Thank you for working on this.  This technology is quite a long way outside of
>> my expertise, and hence my review is primarily focused on the Configuration
>> section (section 9).
>> 
>> Nit: when used with the following interface =>  when used with the following
>> OpenAPI interface
> Fixed
>> 
>> Nit: with a corresponding a entry point -> with a corresponding entry point
> Fixed
>> 
>>  Minor version definitions
>>  SHALL only add objects, non-required members of existing objects, and
>>  non-mandatory-to use functions and SHALL NOT delete any objects,
>>  members of objects or functions.
>> 
>> Would "delete or change" be more correct than just "delete" here?
> Added “or change"
>> 
>> Somewhat related to the discuss comment, but it wasn't clear to me why the
>> versioning is described as part of the "Rue Provider Selection" section and I
>> think that the document would arguably be clearer if the versioning moved to
>> its own separate 9.X section, making it clear that the versioning applies to
>> the entire API?
> I will do that
> 
>> 
>> Nit: The method the API Key is obtained is not specified in this document. =>
>> Perhaps "The method used to obtain the API key …"
> Fixed
>> 
>>  The provider MAY refuse to provide service to an implementation
>>  presenting an API Key it does not recognize.
>> 
>> Why is this not a MUST?
> Well, suppose a provider doesn’t implement an API key, but the client supplies one.  That would not be recognized by the provider, but it doesn’t care, so it provides service.
> 
>> 
>> Is the "instance-identifier" arbitrarily chosen by the client?  Otherwise, it
>> wasn't clear to me how a client would discover or know what
>> "instance-identifier" to use.  It might be helpful if the text clarified this,
> I added that text
> 
>> and possibly even the parameter name could be changed to make it more obvious
>> that it is a client provided value?
> “clientInstanceId” wouldn’t help.  It would have to be “clientProvidedInstanceId”.  That seems to be a bit much as a parameter name.  I’ll do it if you think it’s important, but I’m inclined to just leave the explanatory text specifying that it’s client provided.
>> 
>> Regards,
>> Rob

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Thu, 20 Jan 2022 14:57:55 +0000

Hi Brian,

Thanks for the comments and sorry for the slow reply.

> -----Original Message-----
> From: Brian Rosen <[email-masked]>
> Sent: 23 December 2021 21:16
> To: Rob Wilton (rwilton) <[email-masked]>
> Cc: The IESG <[email-masked]>; [email-masked]; rum-
> [email-masked]; [email-masked]; Paul Kyzivat <[email-masked]>
> Subject: Re: Robert Wilton's Discuss on draft-ietf-rum-rue-09: (with DISCUSS
> and COMMENT)
> 
> It has to be truly optional.  You can do things like add two parameters, a and
> b, and say if a is provided b must be provided, but it has to work if neither
> are there, and even if an implementation provided a but not b, an earlier
> version would ignore a.

Okay.  Thanks for confirming.

> First of all, the Provider list is not available at alll providers.  It’s only available
> at a service that is one per country.  So one entity normally doesn’t supply
> both the Provider and the ProviderConfig entry points.
> To be really pedantic, I suppose that it’s actually possible for it to be one
> entity, and then that statement that there are separate versions wouldn’t
> apply.  So I guess I will change the text to:
> Unless the per-country provider list service is operated by a provider at the
> same base URI as that provider’s configuration service, the version of the
> configuration service MAY be different from the version of the provider list
> service.

This proposed resolution text is fine with me, so I'll clear my discuss.

Alternatively, you could make it state that the versioning information applies to APIs at the same base URI, so if both are available at the same URL end point then they must be the same version, but otherwise they are allowed to be different.

> Well, suppose a provider doesn’t implement an API key, but the client
> supplies one.  That would not be recognized by the provider, but it doesn’t
> care, so it provides service.

Okay.

> “clientInstanceId” wouldn’t help.  It would have to be
> “clientProvidedInstanceId”.  That seems to be a bit much as a parameter
> name.  I’ll do it if you think it’s important, but I’m inclined to just leave the
> explanatory text specifying that it’s client provided.

Just adding the explanatory text is fine with me.  Thanks for checking.

Regards,
Rob