Re: [Gen-art] Gen-ART review of draft-ietf-core-etch-02

[Christer Holmberg <[e-mail]>]

Hi Peter,

I am happy with your reply, so I'll wait for the updated version of the draft :)

Regards,

Christer

-----Original Message-----
From: peter van der Stok [mailto:[e-mail]] 
Sent: 28 September 2016 13:34
To: Christer Holmberg <[e-mail]>
Cc: [e-mail]; [e-mail]
Subject: Re: Gen-ART review of draft-ietf-core-etch-02

Hi Christer,

Thanks for your suggestions and comments.
A bit late reaction due to holidays.

See my answers below. It is not excluded that my co-author may refine
(improve) my answers.

Peter

Christer Holmberg schreef op 2016-09-20 13:34:
> I am the assigned Gen-ART reviewer for this draft. For background on 
> Gen-ART, please see the FAQ at 
> <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>
> 
> Document:               draft-ietf-core-etch-02
> Reviewer:               Christer Holmberg
> 
> Review Date:            20 September 2016
> IETF LC End Date:        7 September 2016
> IETF Telechat Date:     13 October 2016
> 
> 
> Summary:
> 
> The document is well written, and is almost ready for publication as 
> standards track RFC. However, I have a number of editorial issues that 
> I¹d like the authors to address.
> 
> Major Issues:           None
> 
> Minor Issues:           None
> 
> Editorial Issues:
> 
> 
> Q1 (Abstract):
> 
> The Abstract says:
> 
>           "The existing Constrained Application Protocol (CoAP) 
> methods only allow access to a
>            complete resource, not to parts of a resource.²
> 
> I suggest to say ³The CoAP methods  defined in RFC 7252 only 
> allowŠ²Because as possible new CoAP methods are defined in the future, 
> the ³existing methods² statement may no longer be true. This also 
> makes it clear that, when the document was written, RFC 7252 was the 
> only spec you used as input for existing methods.

<pvds> True </pvds>
> 
> 
> Q2 (Abstract):
> 
> In general, I think the Abstract contains too much detail. Wouldn¹t it 
> be enough to keep the 1st paragraph, and add the first paragraph of 
> section 1?
> 
> Something like:
> 
>           "The Constrained Application Protocol (CoAP) methods defined 
> in RFC 7252 only
>            allow access to a complete resource, not to parts of a 
> resource.  In
>            case of resources with larger or complex data, or in 
> situations where
>            a resource continuity is required, replacing or requesting 
> the whole
>            resource is undesirable.  Several applications using CoAP 
> will need
>            to perform partial resource accesses.
> 
>            This specification defines the new Constrained Application 
> Protocol (CoAP)
>            methods, FETCH, PATCH and iPATCH, which are used to access 
> and update parts
>            of a resource.²
> 
> The rest of the Abstract text belongs e.g., in the Introduction 
> section, in my opinion.
<pvds>
IMO, you are right, and your suggestion is an improvement </pvds>
> 
> 
> Q3 (Introduction):
> 
> I think you need more background text before you start talking about 
> the methods. As suggested in Q2, move some text from the Abstract to 
> the Introduction.
<pvds>
will do, but I like to keep the fetch and patch introductions separate as they are.
</pvds>
> 
> 
> Q4 (Section 2):
> 
> The text says: "Implementations MAY use a request body of any content 
> type with the FETCH method;²
> 
> First, I am not sure whether ³MAY² (uppercase) is appropriate here. 
> What
> about saying ³can² och ³may² (lowercase)?
<pvds>
We mean "MAY" as we can envisage different content formats for the future (e.g. one including query specifications) and we have a concrete case today.
</pvds>
> 
> Second, would it be better to say ³attach a body² instead of ³use a 
> body²?
<pvds> I have no opinion on this, may be Carsten? </pvds>
> 
> Third, I think it would be good to add text about "safe and 
> idempotent² also to the Security Considerations section.
<pvds>
That would go to section 1 before section 1.1; to provide the background.
</pvds>
> 
> 
> Q5 (Section 2.2.2):
> 
> Please add reference for Content-Format option.
<pvds> section 5.10.3 to be added</pvds>
> 
> 
> Q6 (Section 2.5):
> 
> Is there a reason this text is not in Section 4?
<pvds>
section 2.5 is about FETCH, while section 4 is about having 3 methods.
Renaming section 4 to "CoAP method set" may help?
<pvds>
> 
> 
> Q7 (Section 2.6):
> 
> First, why not simply calling the section ³Example² or ³FETCH Example²?
> The same comment apply to
> section 3.1 for PATCH/iPATCH examples.
<pvds>
The examples are really simple, and we did not want to raise too high expectations.
May be I am over sensitive on this point.
Just "<Method> example" will do as well.
</pvds>
> 
> Second, is the first paragraph really Example text? Isn¹t it normative 
> text that should be somewhere else?
<pvds>
I like the suggestion to put it before section 2.1 or generate a separate subsection.
</pvds>
> 
> Third, is a reference for JSON needed on first occurrence?
<pvds>
Agree; good catch
</pvds>
> 
> Fourth, I don¹t think you need to say ³might² in the "JSON document 
> that might be returned by GET² sentence. It¹s an example, so simply 
> say "JSON document returned by GET².
<pvds>
agree
</pvds>
> 
> 
> Q8 (Section 2 general):
> 
> Is there a reason there is no ³Error Handling² subsection for FETCH?
<pvds>
section 2.1 is sufficient in this case, because there are no issues that we are aware of.
</pvds>
> 
> 
> Q9 (Section 3):
> 
> As far as I know, HTTP (and CoAP, I assume) method names are case 
> insensitive. Even though it sounds cool and trendy, so you really need 
> to say ³iPATCH², and not ³IPATCH²? Implementers may not thing that one 
> MUST use lowercase ³i², which I assume is not correct, and I am not 
> aware of any other HTTP methods (or SIP, RTSP etc methods) where one 
> would mix
> upper- and lower case in the method name.
<pvds>
Yes, the small "i" looks more sexy on iPATCH.
But I do understand your implementer arguments.
Unless Carsten sees this differently, I like to change to IPATCH as suggested.
</pvds>
> 
> 
> Q10 (Section 4):
> 
> I think you should use another section name than ³Discussion².
<pvds>
"CoAP method set" is suggested under Q6.
</pvds>