From: Christer Holmberg <christer.holmberg@ericsson.com>
To: "draft-ietf-core-etch.all@tools.ietf.org"
 <draft-ietf-core-etch.all@tools.ietf.org>, "gen-art@ietf.org"
 <gen-art@ietf.org>
Thread-Topic: Gen-ART review of draft-ietf-core-etch-02
Thread-Index: AQHSEzL7H/uLk1/jfUWiuM/M60qe/Q==
Date: Tue, 20 Sep 2016 11:34:43 +0000
Message-ID: <D406EE70.F724%christer.holmberg@ericsson.com>
Accept-Language: en-US
Content-Language: en-US
user-agent: Microsoft-MacOutlook/14.6.5.160527
Content-Type: text/plain; charset="Windows-1252"
Content-ID: <DB51891C1296C846BCB470137F36AEE0@ericsson.com>
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
Archived-At: <https://mailarchive.ietf.org/arch/msg/gen-art/8KNNyFfEp05RiY3suGvpeywrsD4>
Subject: [Gen-art] Gen-ART review of draft-ietf-core-etch-02
Precedence: list


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
=20

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=B9d 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.=B2

I suggest to say =B3The CoAP methods  defined in RFC 7252 only
allow=8A=B2Because as possible new CoAP methods
are defined in the future, the =B3existing methods=B2 statement may no long=
er
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.


Q2 (Abstract):

In general, I think the Abstract contains too much detail. Wouldn=B9t it be
enough to keep the 1st paragraph, and
add the first paragraph of section 1?

Something like:  =20

          "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)=20
           methods, FETCH, PATCH and iPATCH, which are used to access and
update parts=20
           of a resource.=B2

The rest of the Abstract text belongs e.g., in the Introduction section,
in my opinion.


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.


Q4 (Section 2):

The text says: "Implementations MAY use a request body of any content type
with the FETCH method;=B2

First, I am not sure whether =B3MAY=B2 (uppercase) is appropriate here. Wha=
t
about saying =B3can=B2 och =B3may=B2 (lowercase)?

Second, would it be better to say =B3attach a body=B2 instead of =B3use a b=
ody=B2?

Third, I think it would be good to add text about "safe and idempotent=B2
also to the Security Considerations section.


Q5 (Section 2.2.2):

Please add reference for Content-Format option.


Q6 (Section 2.5):

Is there a reason this text is not in Section 4?


Q7 (Section 2.6):

First, why not simply calling the section =B3Example=B2 or =B3FETCH Example=
=B2?
The same comment apply to
section 3.1 for PATCH/iPATCH examples.

Second, is the first paragraph really Example text? Isn=B9t it normative
text that should be somewhere else?

Third, is a reference for JSON needed on first occurrence?

Fourth, I don=B9t think you need to say =B3might=B2 in the "JSON document t=
hat
might be returned by GET=B2 sentence. It=B9s
an example, so simply say "JSON document returned by GET=B2.


Q8 (Section 2 general):

Is there a reason there is no =B3Error Handling=B2 subsection for FETCH?


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 =B3iPATCH=B2, and not =B3IPATCH=B2? Implementers may=
 not
thing that one MUST use lowercase =B3i=B2, 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.


Q10 (Section 4):

I think you should use another section name than =B3Discussion=B2.