Subject: [core] Review of core-interfaces-12

From: Christian M. Amsüss <[email-masked]>
Date: Mon, 23 Jul 2018 11:55:56 +0200

Hello core-interfaces authors,

these are my views on core-interfaces-12 as promised in London:

Gradual reveal and RFC6690
==========================

What are the supposed semantics of the links in examples 3 and 4 of 3.6?

If, being fetched from a collection at /coll/, they are

* </coll/temp>;anchor="/coll/" and </coll/temp>;anchor="/sen/",
  respectively, then you're not using RFC6690 link format but
  Modernized Link Format as described in resource-directory; if they are

* </coll/temp>;rt="temperature" and </sen/temp>;anchor="/sen/", then
  you're using the mental model I had of RFC6690 before Jim discovered
  in London that RFC6690 Section 2.1 says Origin with a capital O.

My recommendation is to explicitly use a RFC8288 compatible
interpretation by saying that all link-format documents on the core
interfaces are to be interpreted as Modernized Link Format (better names
still welcome) as described in resource-directory. (The second best
option IMO would be to follow RFC6690 to the letter and have all links
relative to the host root directory aka Origin).

SenML and base names
====================

The SenML components appear to assume that the Base Name (bn) is implied
to be the obtained document's URI; this is no longer the case since
SenML -08[1].

Thus, a batch (like the example in 4.2) would need to have a
"bn":"coap://example.com/s/" attribute in its first entry. Linked
batches can not have their requested URI in that place (as SenML rules
are only about string concatenation; if applications think in URIs, they
must accomodate that), so their bn must be "coap://example.com". Thus,
appending "/s/light" gives a good URI again.

[1]: Until -07, it said that "If the object is a representation
   resulting from the request of a URI [RFC3986], then in the absence of
   the Base Name attribute, this URI is used as the default value of
   Base Name.

Assorted
========

* Updating links with merge-patch and PATCH ("Links in the collection
  MAY be"): Is this fully thought through? In RD we decided to delay
  that part until someone figures out how to correctly manipulate parts
  of a collection. The approach of putting query filtering in is
  interesting, but doesn't paint a full picture to me.

  With query filtering, can I delete a single link from an lb using
  `DELETE /linkedbatch/?href=/s/1`?
  
  Is the client in a linked batch supposed to provide any attributes to
  the links? (If not, what changes warranting a merge-patch can there be
  made other than adding and removing links?)

* 3.7: Whether a collection implements link filtering should be
  discoverable in some way IMO. How about additional if="core.filter" on
  those that do?

  If that is not get advertised, the least that should be done is to say
  that query parameters MUST be ignored by collections if querying is
  not supported. (As it is with .well-known/core: Support is optional,
  but if a GET /.well-known/core?rt=foo comes along and the server can't
  filter, it does the safe thing and returns the complete set.) That's
  for reading; PUT/POSTing to a filtered query without filter support
  should be 4.02 Bad Option.

* Actuators: Is every actuator supposed to support some POSTs? If not,
  I'd put the POST in Table 2 as optional.

  Similarly: May an actuator be write-only, and return Method not
  supported to a GET?

* Security considerations: A linked batch can write to arbitrary
  resources on the server; considerations say something about whether
  it's the creator of the link batch or the writer who needs to have
  authority to write to linked resources. (It's a bit like with
  dynlinks, with only moderate mitigation by foreign links being
  forbidden. Writing </firmware> to a linked batch and then putting a
  large application/octet-stream there can still go very bad.)

Do I read this right?
=====================

might be illustrated or made more explicit

* 3.5 query filtering (when applied to the items): I like this idea; as
  I understand, I could do on a batch /b/1/ containing

  <light1>;rt="some.rgb";if="core.a",
  <light2>;rt="some.rgb";if="core.a",
  <light3>;rt="some.dimmer";if="core.a"

  do a PUT /b/1/?rt=some.rgb, payload #ffff00, which would set all the
  RGB leds to yellow but leave light3 unaffected?

* In the example of Figure 1, if I did not want to reveal all the /a/
  subresources in a step, would there be anything wrong in saying it's
  if="core.b core.ll"? (Just to verify our common understanding of the
  text).

Small stuff
===========

* "with a Link List /d containing": It's /d/ in the above example

* 3.4 mentions link-format+json, it should probably do the same with
  link-format+cbor

The overall document, esp. having batches, parameters and actuators, has
been stable for quite some time, so I expect that the remaining details
(above and hopefully from other reviewers) can be worked out swiftly fo
finally release this document.

I'd suggest it to be reviewed by authors of SenML fetch/patch; it
appears to me that there is some overlap to be considered.

Best regards
Christian

-- 
I shouldn't have written all those tank programs.
  -- Kevin Flynn