Subject: [regext] AD review of draft-ietf-regext-rdap-partial-response-12

From: Barry Leiba <[email-masked]>
Date: Fri, 24 Jul 2020 14:16:43 -0400

Thanks so much for the recent editorial work on this document:  Version -12
is easy to read and clear, and I’m happy to sent it to last call.  I have
some review comments below, but they’re all minor and can be handled as
part of the last call comments.  I will request last call on this right
after I send this note.

— Section 1 —

   Several leading API providers [LINKEDIN] [FACEBOOK] [GOOGLE]
   implement partial response features by providing an optional query
   parameter through which clients identify the fields they wish to
   receive.  Support for partial responses is also considered a leading
   principle by many best practice guidelines in REST API implementation
   [REST-API1] [REST-API2] in order to improve performance, save on
   bandwidth and possibly accelerate the overall interaction.  In other
   contexts, for example in digital libraries and bibliographic
   catalogues, servers can respond according to different element sets
   (i.e. "brief" to obtain a short response and "full" to obtain the
   complete response).

Maybe it’s just me, but I find that paragraph unnecessary.  I suggest
simply removing it (and the references it cites) as extraneous.  This is a
suggestion, not a requirement, so if the working group has a reason to keep
the paragraph, that’s OK.  I just think it doesn’t add anything useful to
the document beyond what’s in the other paragraphs here.

— Section 1.1 —
Please use the exact boilerplate from RFC 8174.

— Section 4 —

   o  "id": the server provides only the key field, respectively:
      "handle" for entities, "ldhName" for domains and nameservers.

Nit: Please remove “, respectively”, as it’s misused here.  Correct use
(though I don’t suggest this change) woud be, ‘the server provides only the
key field: “handle” or “ldhName” for entities or domains and nameservers,
respectively.’

   RDAP providers are RECOMMENDED to include

This is correct and fine as written, but I think it reads better in active
voice as, “RDAP providers  SHOULD include”.

   Fields included in the "brief" and "full" field sets MUST be returned
   according to the user's access and authorization levels.

What is the focus of this sentence?  Is it about what MUST be returned?  Or
that authorization levels MUST be applied?  I think it’s the latter, but
it’s not clear from the wording.  If I’m right, it might be better worded
this way (adjust as appropriate to give the emphasis you really intend):

NEW
   Fields included in the "brief" and "full" field set responses MUST
   take into account the user's access and authorization levels.
END

— Section 6 —
Please make the contact “IETF”, rather than “IESG”.

—
Barry

---

From: Mario Loffredo <[email-masked]>
Date: Mon, 27 Jul 2020 13:14:53 +0200

Hi Barry,

thanks a lot for your review and feedback. I provide answers to your 
feedback below.

Il 24/07/2020 20:16, Barry Leiba ha scritto:
> Thanks so much for the recent editorial work on this document: 
>  Version -12 is easy to read and clear, and I’m happy to sent it to 
> last call.  I have some review comments below, but they’re all minor 
> and can be handled as part of the last call comments.  I will request 
> last call on this right after I send this note.
>
> — Section 1 —
>
> simply removing it (and the references it cites) as extraneous.  This 
> is a suggestion, not a requirement, so if the working group has a 
> reason to keep the paragraph, that’s OK.  I just think it doesn’t add 
> anything useful to the document beyond what’s in the other paragraphs 
> here.
>
[ML] OK.

I remove the paragraph and update the first paragraph in Appendix A 
accordingly:

OLD

    Looking at the implementation experiences described in Section 1, two
    approaches to the implementation of partial response are observed:

NEW

    Looking at the implementation experiences of partial response, two
    approaches are observed:

— Section 1.1 —

> Please use the exact boilerplate from RFC 8174.
[ML] OK
> Nit: Please remove “, respectively”, as it’s misused here.  Correct 
> use (though I don’t suggest this change) woud be, ‘the server provides 
> only the key field: “handle” or “ldhName” for entities or domains and 
> nameservers, respectively.’
>
[ML] OK
> This is correct and fine as written, but I think it reads better in 
> active voice as, “RDAP providers  SHOULD include”.
>
[ML] OK
> What is the focus of this sentence?  Is it about what MUST be 
> returned?  Or that authorization levels MUST be applied?  I think it’s 
> the latter, but it’s not clear from the wording.  If I’m right, it 
> might be better worded this way (adjust as appropriate to give the 
> emphasis you really intend):
>
> NEW
[ML] Sounds better.
> Please make the contact “IETF”, rather than “IESG”.
[ML] OK

Best,

Mario

> —
> Barry
>
>
> _______________________________________________
> regext mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/regext

-- 
Dr. Mario Loffredo
Systems and Technological Development Unit
Institute of Informatics and Telematics (IIT)
National Research Council (CNR)
via G. Moruzzi 1, I-56124 PISA, Italy
Phone: +39.0503153497
Mobile: +39.3462122240
Web: http://www.iit.cnr.it/mario.loffredo

---

From: Barry Leiba <[email-masked]>
Date: Mon, 27 Jul 2020 18:17:37 -0400

Thanks for the quick response, Mario.  All good -- when you've
addressed all the last call comments, post a revised I-D... it can
wait until the end of the last call period.

Barry

On Mon, Jul 27, 2020 at 7:17 AM Mario Loffredo
<[email-masked]> wrote:
>
> Hi Barry,
>
> thanks a lot for your review and feedback. I provide answers to your feedback below.
>
> Thanks so much for the recent editorial work on this document:  Version -12 is easy to read and clear, and I’m happy to sent it to last call.  I have some review comments below, but they’re all minor and can be handled as part of the last call comments.  I will request last call on this right after I send this note.
>
> — Section 1 —
>
> Maybe it’s just me, but I find that paragraph unnecessary.  I suggest simply removing it (and the references it cites) as extraneous.  This is a suggestion, not a requirement, so if the working group has a reason to keep the paragraph, that’s OK.  I just think it doesn’t add anything useful to the document beyond what’s in the other paragraphs here.
>
> [ML] OK.
>
> I remove the paragraph and update the first paragraph in Appendix A accordingly:
>
> OLD
>
> Nit: Please remove “, respectively”, as it’s misused here.  Correct use (though I don’t suggest this change) woud be, ‘the server provides only the key field: “handle” or “ldhName” for entities or domains and nameservers, respectively.’
>
> [ML] OK
>
> This is correct and fine as written, but I think it reads better in active voice as, “RDAP providers  SHOULD include”.
>
> [ML] OK
>
> What is the focus of this sentence?  Is it about what MUST be returned?  Or that authorization levels MUST be applied?  I think it’s the latter, but it’s not clear from the wording.  If I’m right, it might be better worded this way (adjust as appropriate to give the emphasis you really intend):
>
> NEW