Does mason support embedded resources?

[nick.p...@gmail.com]

Sorry if this has been asked and answered, I couldn't find the answer via a web search.  I've seen a couple articles say that mason is a superset of hal yet I didn't see support for embedded resources in the spec.  Does mason support embedded resources?

Thanks,
Nick

[Jørn Wildt]

Hi,

Mason can do embedded (just like any other JSON payload can do it), but it is not part of the spec. You can for instance have an array of embedded items like this:

{

  "title": "This is a collection of embedded items, each of which has a link to its full representation",

  "items":
  [
    {

      "title": "Item 1 (embedded, partial representation)",

      "p1": "Some property of item 1",

      @controls
      {
        "self": { "href": "..." }
      }
    },
    {

      "title": "Item 2",

      "p1": "Some property of item 2",

      @controls
      {
        "self": { "href": "..." }
      }
    }
  ]

  @controls
  {

    "self": { "href": "..." }

  }

}

The syntax used is from version 2 of the spec. The main change here is that all "@links", "@link-templates" and "@actions" are combined into a single "@controls" element. See https://github.com/JornWildt/Mason/blob/master/Documentation/Mason-draft-2.md

--
You received this message because you are subscribed to the Google Groups "Mason media type" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mason-media-ty...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[nick.p...@gmail.com]

Hmmm, that doesn't sound like embedding.  Is there a way a client will be able to tell where the resource starts/ends and where the embedding begins with this design?  Of course the question to me might be: "why do you need to know?" and I don't have an answer for that yet.  I have yet to write a hypermedia client, just as the investigation stage.

Thanks,
Nick

[Jørn Wildt]

I think I saw your question being answered on the HAL discussion list, right? In short: "embedded" in HAL allows intelligent standard clients to ignore the difference between using a link to GET a resource or simply read the expected value embedded in the response.

There are good and bad stuff to say about it as discussed here: https://groups.google.com/d/msg/hal-discuss/DubyH0A7nnQ/hrvsAm7bcDAJ.

So far I prefer Mason to be without explicit "embedded" support.

/Jørn

[nick.p...@gmail.com]

Yeah, I was going to reply to this after getting some info on the hal group regarding embeddings.

I'm now thinking that embedded objects, and by that I mean specifically supported by the media type, are important.  Let's say I have the documentation for a resource, maybe an order.  And that tells me that a customer is a related resource and the link relation for that is customer.  It would seem to make sense that a client is going to either look for a link with that link relation or an embedded resource with that link relation, not an embedded object, especially since I might not even be able to name the object with the same name as the link relation, lets say if the link relation is a URL.

Thanks,
Nick

[Jørn Wildt]

There are a few similar discussions going on in the HAL list. The idea of embedded seems simple at first - but then it leads to confusion when you start considering partial/incomplete/different embedded resources. See https://groups.google.com/d/msg/hal-discuss/n-YZ2lr_m_I/-Thw0jhQNsAJ.

Consider this scenario:

- Assuming a semi-intelligent client that is aware of both links and embedded.

- At one time the client receives a resource R1 with a link to another resource R2.

- The client follows that link to GET the R2  resource. At this time the client receives the full representation of R2.

- At a later time the server removes the link and embed the R2 resource in R1 instead.

- Now the client sees that embedded R2 resource and uses that instead ... but can it safely do that? The client was used to GET'ing a *full* R2 representation - now it has an embedded R2 resource, but it has no guarantee about the "completeness" of that R2 as it could be a partial representation of R2 - or even plain different.

So the idea of transparency between links and embedded is a bit tricky.

As long as the HAL guys cannot sort it out - I won't suggest adding it to Mason as a standard feature.

/Jørn

[nick.p...@gmail.com]

I thought someone suggested the logic as:

1. I'm searching for a related resource.
2. Is link relation in embedded?
3. Yes?  goto 4 else goto 9
4. Probe embedded for property(ies) you're looking for.
5. Did you find all the properties?
6. Yes? goto 14 else goto 7
7. Get self link of embedded
8. goto 12
9. Link relation in links?
10. Yes?  goto 11 else goto 14
11. get link from links section
12. get full representation
13. probe for the property(ies)
14. done

Ignore any obvious mistakes I might have made.

Thanks,
Nick

[Jørn Wildt]

Step 4+5 is what annoys me. These steps cannot be generalized and must be carried out in the application layer above the "intelligent" generic client (since the generic client wouldn't be able to know exactly what properties the application would be looking for).

One could although simplify it by including some sort of general "This embedded resource is (in)complete" information in the embedded data - plus expecting the server to guarantee a certain subset of properties to always be in the embedded resource. In that case the application could ask the client for the complete representation, which it would then get from embedded (if complete version was available) or by following the link.

But as someone else said - then you run into problems with some application developers that start complaining about a big bloated response with lots of embedded stuff in it that they do not need. I would rather see different resources (different URLs) with different, documented and guaranteed, properties in them - where each resource covers different use cases. Let the client decided whether to have "embedded" data or not (by choosing different links/URLs/resources) instead of trying to make it transparent and letting the server decide.

/Jørn

[nick.p...@gmail.com]

Actually I seem to like how it works in HAL.  You always assume the embedding might not be "full".  This allows the server to optimize and only include the most requested properties.  Otherwise, the only benefit you'd get by embedding is the cost of the call itself, possibly multiplied by the number of embeddings.  However, if a representation had say 20 properties but the server knows that 98% of the time only 3 are needed, it can only include those three in the embedding.  In 98% of the cases it would have optimized the traffic by only providing those 3 properties.

Also, it would seem the application doesn't need to know about this logic.  A client could be written which when asked for properties of a relation it would first check for it in the embedding and if not found it would get the full representation and check there.

Thanks,
Nick