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

From: Robert Wilton via Datatracker <[email-masked]>
Date: Wed, 15 Dec 2021 04:37:17 -0800

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?

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.

----------------------------------------------------------------------
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

Nit: with a corresponding a entry point -> with a corresponding entry point

   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?

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?

Nit: The method the API Key is obtained is not specified in this document. =>
  Perhaps "The method used to obtain the API key ..."

   The provider MAY refuse to provide service to an implementation
   presenting an API Key it does not recognize.

Why is this not a MUST?

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,
and possibly even the parameter name could be changed to make it more obvious
that it is a client provided value?

Regards,
Rob

---

From: Brian Rosen <[email-masked]>
Date: Thu, 23 Dec 2021 16:16:16 -0500

Thank you for your comments.  Please see inline

> On Dec 15, 2021, at 7:37 AM, Robert Wilton via Datatracker <[email-masked]> wrote:
> 
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.

> 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.

Fixed
> Nit: with a corresponding a entry point -> with a corresponding entry point
Fixed
> Would "delete or change" be more correct than just "delete" here?
Added “or change"
> its own separate 9.X section, making it clear that the versioning applies to
I will do that

>  Perhaps "The method used to obtain the API key …"
Fixed
>   presenting an API Key it does not recognize.
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.

> "instance-identifier" to use.  It might be helpful if the text clarified this,
I added that text

> 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.