Subject: [T2TRG] comments on draft-keranen-t2trg-rest-iot

From: mike amundsen <[email-masked]>
Date: Sat, 9 Apr 2016 17:28:26 -0400

I read through the draft this week and am send along my initial comments
for discussion. I like the notion of providing guidance to IoT developers
and hope this document can be a cornerstone of that effort.

Section 1. Introduction
The intro says this document is meant as guidance for designing IoT systems
that follow the principles of the REST style but those principles do not
appear anywhere in this document nor are the appropriate sections in
Fielding's dissertation noted.

You come close with the following: "RESTful design facilitates many
desirable features for a system, such as good scaling properties." This is
where I'd refer to the full set of "Architectural Properties of Key
Interest" from the dissertation[0]. I think it is then worthwhile to
mention Fielding's requirements[1] (note these are WWW requirements, not
IoT requirements) and the constraints [2] he selects to *induce* the
properties.

The remainder of the document focuses not on archtectural issues, but on
protocol issues and is limited in even this area to focusing on HTTP and
CoAP. I'm not sure if you want to provide protocol guidance or design
guidance and will leave that up to discussion before making any other
comments on this part of the doc.

Section 2 Terminology - no comment for now

Section 3.,1 - no comment

Section 3.2
I suggest using the words "client state" and "resource state" in section
3.2 of draft-keranen-t2trg-rest-iot. This more clearly identifies who is
responsible for which state elements and avoids discussions about
"application" and "session" definitions.

Flow control MAY be managed from either the client ("please set this valve
to position 3") or the resource server ("According to my configuration
data, your client certificate only allows you to do one of the
following...") Rather than try to define "session state" as flow control, I
think it s better the establish lines of responsibility for client state
and resource state.

Section 3.3
I suggest the following updated wording for the opening:
"Important part of designing a system is to model is as a set of resources
which represent the "state of the system." Clients MAY be allowed to modify
the state of resources by passing representations to the server (using
request bodies). Servers manipulate the state of clients by passing
representations of resources (using response bodies)."

Section 3.4
I think most of the text here can be removed and replaced with a reference
to existing RFCs on URI (e.g. 3986). I think it would also be good guidance
to reference RFC7320 ("URI Design and Ownership")[3].

Section 3.5 & 3.6
I think a reference to the relevant RFCs is all that is needed here.
Listing methods here runs the risk of becoming outdated as the list of
valid methods changes over time.

Section 4
I think it's a mistake to call out RFCs here since even media types will
have security considerations and we can't know which types are in use
(including new types as they are created). I suggest something about
"Relavent RFCs" or something here.

I appreciate the oppty to comment and look forward to any follow up
discussions.

thanks.

[0]
https://www.ics.uci.edu/~fielding/pubs/dissertation/net_app_arch.htm#sec_2_3
[1]
https://www.ics.uci.edu/~fielding/pubs/dissertation/web_arch_domain.htm#sec_4_1
[2]
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1
[3] https://tools.ietf.org/html/rfc7320

mamund
Mike Amundsen
+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

---

From: Ari Keränen <[email-masked]>
Date: Sun, 10 Apr 2016 12:43:48 +0000

Hi Mike,

Thanks a lot for your review and comments! Please see inline.

> On 09 Apr 2016, at 18:28, mike amundsen <[email-masked]> wrote:
> 
> I read through the draft this week and am send along my initial comments for discussion. I like the notion of providing guidance to IoT developers and hope this document can be a cornerstone of that effort.
> 
> Section 1. Introduction
> The intro says this document is meant as guidance for designing IoT systems that follow the principles of the REST style but those principles do not appear anywhere in this document nor are the appropriate sections in Fielding's dissertation noted. 
> 
> You come close with the following: "
> RESTful design facilitates many desirable features for a system, such
> 
> as good scaling properties." This is where I'd refer to the full set of "Architectural Properties of Key Interest" from the dissertation[0]. I think it is then worthwhile to mention Fielding's requirements[1]
>  (note these are WWW requirements, not IoT requirements) and the constraints [2] he selects to *induce* the properties.
> 
> 
> The remainder of the document focuses not on archtectural issues, but on protocol issues and is limited in even this area to focusing on HTTP and CoAP. I'm not sure if you want to provide protocol guidance or design guidance and will leave that up to discussion before making any other comments on this part of the doc.

Indeed the requirements and constraints from the Fielding thesis are not explicitly mentioned or discussed in detail in the draft. As discussed in the other thread, not all requirements apply to same extent for IoT cases. Also, we try to keep the information in this draft brief and practical. That said, having a bit more information and pointers on this topic could be appropriate; will have a a look at that. And we are open for discussion what is the right balance here.

> I suggest using the words "client state" and "resource state" in section 3.2 of draft-keranen-t2trg-rest-iot. This more clearly identifies who is responsible for which state elements and avoids discussions about "application" and "session" definitions.
> 
> Flow control MAY be managed from either the client ("please set this valve to position 3") or the resource server ("According to my configuration data, your client certificate only allows you to do one of the following...") Rather than try to define "session state" as flow control, I think it s better the establish lines of responsibility for client state and resource state.

OK; so that would mean using "client state" instead of "session state". Sounds reasonable to me, but I'd like to hear from Matthias and Klaus (and others). We did already spend quite some time discussing what is the right formulation here.

> "Important part of designing a system is to model is as a set of resources which represent the "state of the system." Clients MAY be allowed to modify the state of resources by passing representations to the server (using request bodies). Servers manipulate the state of clients by passing representations of resources (using response bodies)."

Sounds good to me, thanks!

> Section 3.4
> I think most of the text here can be removed and replaced with a reference to existing RFCs on URI (e.g. 3986). I think it would also be good guidance to reference RFC7320 ("URI Design and Ownership")[3].

I think we should keep this text here. This is an area where I have seen lots of confusion with some APIs and I think it's worth spending one page for. Maybe some parts of this could be made more concise; will have a look at that.

But yes, we should add reference to RFC7320.

> Section 3.5 & 3.6
> I think a reference to the relevant RFCs is all that is needed here. Listing methods here runs the risk of becoming outdated as the list of valid methods changes over time. 

Proper used of methods is again one of the practical basics that I've seen many systems getting wrong and hence I think it would be good to have it here, even if it is to large extent identical to RFC 7231 text. If we have only reference, it is likely to be skipped by many readers of the document. But adding a note about the fact that new methods are coming sounds good to me (could perhaps reference PATCH and/or FETCH?).

> Section 4 
> I think it's a mistake to call out RFCs here since even media types will have security considerations and we can't know which types are in use (including new types as they are created). I suggest something about "Relavent RFCs" or something here.

I think references to key RFC sections is more valuable than generic remark here; again in the spirit of giving brief overview and pointers in this draft. But we should perhaps make it more clear that the list is not exhaustive. And have a look at the media types too and add the IoT security considerations draft (draft-irtf-t2trg-iot-seccons).

> I appreciate the oppty to comment and look forward to any follow up discussions.

Thanks again and looking forward to continue discussion on this!

Cheers,
Ari

> thanks.
> 
> 
> [0] https://www.ics.uci.edu/~fielding/pubs/dissertation/net_app_arch.htm#sec_2_3
> [1] https://www.ics.uci.edu/~fielding/pubs/dissertation/web_arch_domain.htm#sec_4_1
> [2] https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1