Re: [apps-discuss] JSON-Home widget example

[Mark Nottingham <[e-mail]>]

Hi Jan,

This isn't really specific to home; it's about collections and link relations. It came up some when we were doing 5988, IIRC.

There are a couple of ways of dealing with it. 

One would be to have a "collection" link relation and then put a parameter on it that says what it contains.

E.g., as a HTTP header, it would be:
  Link: </widgets>; rel="collection"; contains="http://example.org/rel/widget"

However, in JSON Home, this becomes:

     "collection": {
        "href": "/widgets/",
        "contains": "http://example.org/rel/widget"
      },
      "http://example.org/rel/widget": {
        "href-template": "/widgets/{widget_id}",
        "href-vars": {
          "widget_id": "http://example.org/param/widget"
        },
        ...
      }

which isn't great, because you can then have only one collection type in your API! It also means that a *lot* of identifying information is lost from the link relation type. If we allowed multiple collection relation types to be defined (for example, by making its value an array of objects), it would introduce an extra layer of dispatch, which isn't great.

If you turn that inside-out, you might end up with something like:

      "http://example.org/rel/widget": {
        "href-template": "/widgets/{widget_id}",
        "href-vars": {
          "widget_id": "http://example.org/param/widget"
        },
        "container": "/widgets/"
      }

This is succinct, but I'm wary, because the container is "hidden" inside the widget type, and you now need to *very* precisely define the semantics of "container"; if you want to vary from it even a little bit, you're out of luck, because there's no space for adorning it with hints, etc. This approach also precludes mixing different things in the same container (at least obviously).

The way I look at it, what you're asking for here is syntactic sugar. In English, we have separate names for "jar" and "candy" because they're separate things, even though they're often used together.

While it's tempting to define the primitive "jar of candy", I don't want to *start* there, because it'll severely limit the expressiveness of the format, and create awkward special/corner cases.

So, I suspect that we'll always need two relation types to accurately talk about things vs. containers of things. 

That's not to say that we don't need something here, of course; IIRC there is a TODO in the spec for precisely this. I'm just not quite at the point where I know what it looks like. If I had to take a stab now, it'd be something like:

     "http://example.org/rel/widget": {
        "href": "/widgets/",
        "contains": "http://example.org/rel/widget"
      },
      "http://example.org/rel/widget": {
        "href-template": "/widgets/{widget_id}",
        "href-vars": {
          "widget_id": "http://example.org/param/widget"
        },
        ...
      }

Does that make sense? 

Cheers,






On 08/04/2013, at 9:11 PM, Jan Algermissen <[e-mail]> wrote:

> Hi Mark,
> 
> curious about your opinion on the following.
> 
> The example you provide in the draft[1] troubles me a bit since a real-life, similar case made me look at it from a different angle.
> 
> 
>    "http://example.org/rel/widgets": {
>         "href": "/widgets/"
>       },
>       "http://example.org/rel/widget": {
>         "href-template": "/widgets/{widget_id}",
>         "href-vars": {
>           "widget_id": "http://example.org/param/widget"
>         },
>         ...
>       }
> 
> What we have here is sort of a standard pattern for making available 'a bag of things' via HTTP.
> 
> For example, a bunch of orders can be straight forward exposed as
> 
>  /orders
> 
> and knowing that
> 
>  "http://example.org/rel/orders" : { "href" : "/orders" }
> 
> pretty much implies something like /orders/{orderId}, including the idea that adding an order is likely done with a POST to /orders and that editing an order is (maybe) achieved with PUT/PATCH/DELETE.
> 
> What troubles me is that JSON Home currently makes it necessary to define two link relations to cover a standard (in a sense) use case that could be covered with just one link relation. Or, in other words, the two link rels somehow semantically overlap, yet demand two 'specifications'. Think in terms of violating DRY.
> 
> Can't think of an improvement that does not introduce the 'pattern' into the spec, but I am nevertheless much interested in your view.
> 
> Maybe an optional {widget_id} and one rel with appropriate definition does the trick already, but hard to seperate the hints. Dunno...
> 
> Jan
> 
> [1] http://tools.ietf.org/html/draft-nottingham-json-home-02
> 

--
Mark Nottingham   http://www.mnot.net/