Clarify connection between URL namespace and JSON structure

[jernst]

There appears to be a connection at the hip between the names of the URLs below a Thing's root URL, and entries in JSON documents served from URLs further up. This connection should be generalized and documented.

Suggestion: define all the "atomic" interactions at lower-level URLs first. Then, look whether efficiencies can be gained by packaging several of those "atomic" interactions into a compound one at a higher-level URL. If so, use the documented generic scheme, e.g. "if you perform HTTP GET on each of ROOT/foo/1 to ROOT/foo/27", and concatenate the results into a JSON array, it will produce the same result as if you HTTP GET on ROOT, JSON entry "foo".

[benfrancis]

I'm not sure exactly what you mean.

The Thing Description is intended as the root level resource for describing a thing, with links to sub-resources representing its properties, actions and events.

There are also properties, actions and events URLs in the links section which let you get all properties at the same time for example.

In the example below...

{
  'properties' : {
    '1': { 'href': '/things/foo/properties/1' },
    '2': { 'href': '/things/foo/properties/2' },
    '3': { 'href': '/things/foo/properties/3' },
  },
  'links': [
    {
      'rel': 'properties',
      'href': '/things/foo/properties
    }
  ]
}

...getting /things/foo/properties will in fact give you a JSON response which combines the content of /things/foo/properties/1, /things/foo/properties2, and /things/foo/properties3. This is already documented. Does this not already do what you're describing?

Note that the spec is generally more optimised for developer usability rather than efficiency, but with some optimisations (like being able to get all properties at once).

[jernst]

I think you are applying (and I'm not disagreeing) a pattern for how the JSON is supposed to look like at different endpoint, taking into account the relationship between the URLs of the endpoints. If so, I suggest this pattern can and should be documented, so as people extend the API, they continue following the same pattern. That's all. I'm not asking for additional or different functionality.