Is Anyone Using Embedded Link Sub-Entities?

[Kevin Swiber]

Howdy everyone,

As I was reviewing my own usage of Siren over the last (nearly) 4 years, I realized something important.  The only time I've ever used an embedded link sub-entity was during an initial prototype that led to the first draft of the Siren specification.

Since that time, my preference has been to opt for an embedded representation sub-entity that provides a sort of "list view item" of the sub-entity.  If such a thing isn't helpful, the affordance I end up using is the "links" array.

Is anyone using embedded link sub-entities in their API?  If so, do you find it a helpful affordance?

https://github.com/kevinswiber/siren#embedded-link

Thanks,

Kevin

[Michael Tiller]

To be honest, I don't really understand that part of the spec.  It sounds like an embedded resource has a rel and an embedded link has a rel and an href?  Is that the difference?  I was always confused by that part of the spec.

--

Mike

--
You received this message because you are subscribed to the Google Groups "Siren Hypermedia" group.
To unsubscribe from this group and stop receiving emails from it, send an email to siren-hypermed...@googlegroups.com.
To post to this group, send email to siren-hy...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CAGA7vN6pHA9BbgMv2G47CvqLcE59YDqDArywS0Bx0qWv008tTQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Manuel Gómez]

On Sat, Apr 23, 2016 at 1:19 PM, Kevin Swiber <ksw...@gmail.com> wrote:
> Is anyone using embedded link sub-entities in their API? If so, do you find
> it a helpful affordance?

Yes. I find it helpful to provide options in resources to leave
embedded entities as mere links, or to expand them. This allows using
simpler, faster database queries and smaller response payloads for
paged collection resources when the application knows it has no need
for details on the collection’s elements, and with a simple query
parameter to the same backend handler, refer to another similar
collection but with embedded entities expanded partially or fully,
even sometimes recursively so to various levels for resources with
hierarchical structure.

[Kevin Swiber]

Mike,

That's a common response.  :)

An Embedded Link Sub-Entity is a lightweight affordance that simply points the client to a URL for retrieving the Sub-Entity.  An Embedded Representation Sub-Entity allows an affordance for including important information about the Sub-Entity (properties, actions, links, [even sub-sub-entities but that gets wacky]).  In my experience, I often express an abbreviated representation in a "list view item" context, and following the Sub-Entity's "self" link returns the full representation.  I do this using the Embedded Representation style.

- Kevin

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CANmMiBa2cBE%3DBNJb%2B83Lu%3DUPt2EK0L5pWn2ijGa_NOy%3D8QgQPg%40mail.gmail.com.

[Michael Tiller]

But I don't understand the difference in terms of the specification.  They are both included in "entities", right?  Is the difference in the required fields.  From the example on the Siren repo, it seems like the embedded link has "href" and nothing else while the embedded resource doesn't have the href but is a full resource.

It would be useful if there were actually a defined JSON Schema for Siren because I always interpreted the spec as "an embedded resource has everything a root resource has but also includes a rel and href in addition".  But it seems like I misunderstood this (which is the danger of prose vs. a formal schema).

--

Mike

[Kevin Swiber]

Yes, they are both included in "entities."  Yes, there's a difference in the required fields, as you stated.

I'll work on a JSON Schema.  Stephen Mizell started working on an MSON description, which might be a good starting place for me.  I like the mixture of documentation and schema.  https://gist.github.com/smizell/dd76e4e93bef3f17815feded7fcd2881

--
You received this message because you are subscribed to the Google Groups "Siren Hypermedia" group.
To unsubscribe from this group and stop receiving emails from it, send an email to siren-hypermed...@googlegroups.com.
To post to this group, send email to siren-hy...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CANmMiBaChC1kHv5XHy64i7aEE5xEUycBHJxGL%2B4eVrn7cx8acg%40mail.gmail.com.

[Alex Soto]

I use json-schema as part of my api acceptance tests to validate the format of my responses.

It's not a tremendous amount of stuff, but I can provide them if interested to get the ball rolling.

Alex

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CAGA7vN5O20eh1gYw8za0vOWi8rMbHEhysj%3Djyj4DT59aqzpziw%40mail.gmail.com.

[Michael Tiller]

A JSON Schema would be much appreciated. Even better would be a pull request that adds it to the Github repo. ;-)

Kevin, would you accept such a PR?

--
Mike

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CABEd5qN60K2T8XqGgA-y2dTUujdjZGNmMQumXcjjzZnEwyc5VA%40mail.gmail.com.

[Dietrich Schulten]

Hi Kevin,

Am Samstag, 23. April 2016 19:50:05 UTC+2 schrieb Kevin Swiber:

Howdy everyone,

As I was reviewing my own usage of Siren over the last (nearly) 4 years, I realized something important.  The only time I've ever used an embedded link sub-entity was during an initial prototype that led to the first draft of the Siren specification.

Since that time, my preference has been to opt for an embedded representation sub-entity that provides a sort of "list view item" of the sub-entity. 

Could you provide a sample for this? My limited imagination cannot follow ;-)

Best,

Dietrich

[Kevin Swiber]

Update:

Here's a JSON Schema for Siren: https://gist.github.com/kevinswiber/14477759858a768d2809326ca4300d26

It includes support for this Pull Request for checkbox/radio field values: https://github.com/kevinswiber/siren/pull/69/files

Here's the relevant Sub-Entity section: https://gist.github.com/kevinswiber/14477759858a768d2809326ca4300d26#file-siren-schema-json-L34-L78

[mca]

Kevin:

when adding support for new UI fields (checkbox/radio) I *assume* these are all optional for existing client apps, right? 

IOW, my current client is not now a "non-compliant" Siren client because I don't support checkbox/radio, correct?

mca

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

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CAGA7vN6emvhg5urqqi1ahqoM6SQY1d0ccJwc1hd-Hz9iL8ub4g%40mail.gmail.com.

[Kevin Swiber]

There's some thread cross-over here.

The client would have had to be built to ignore unknown field value types.  Otherwise, introducing a checkbox/radio field in the API response (as defined by that Pull Request) might cause an error to be thrown by the client.

This particular change is tricky, because it represents an unspecified part of Siren actually receiving attention after quite some time living in a gray area.

A small clarification for posterity: I don't consider "checkbox" or "radio" fields to be UI-specific.  Neither does HTML5.  Looking at how input type=checkbox is defined: "The input element represents a two-state control that represents the element's checkedness state. If the element's checkedness state is true, the control represents a positive selection, and if it is false, a negative selection"[0]

[0] https://www.w3.org/TR/html5/forms.html#checkbox-state-(type=checkbox)

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CAPW_8m54iWCeW_kW0HQMkm0kuBFnjNKGefgCM09Nhwb1LiM9_w%40mail.gmail.com.

[mca]

yeah - sorry. i'll take this to the proper thread.

cheers.

mca

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

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CAGA7vN6vOQQYHa3Oiq6vOd5_6mXOgaXZ-X%3DR2-iLCPsjf%2BihCQ%40mail.gmail.com.

[Kevin Swiber]

FYI: Found a couple of errors in the JSON Schema.  I'm still a JSON Schema novice.  I fixed the issues and added descriptions to everything.

https://gist.github.com/kevinswiber/14477759858a768d2809326ca4300d26

[Michael Tiller]

Wouldn't it be better to put the JSON in the repo itself instead of in a Gist?

--

Mike

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CAGA7vN6HAyAJrcc28iFx4v6-j-Zh%2BXwz3%3Dynp%2BUFwTGfpob3gg%40mail.gmail.com.

[Pim Kartner]

We are using it in production to lazyload entities with a picture encoded in it. So yes, I think it can be very usefull in some instances.

[Michael Tiller]

I just used your JSON Schema to create TypeScript definitions for Siren entities, etc.

You can find the latest version of the TypeScript definitions here:

https://github.com/xogeny/siren-types/blob/master/src/index.ts

For anybody using TypeScript, you can grab these definitions with just 'npm install siren-types' (I may add some functions in the future as well for working with Siren data but for now it is just types...so it is completely useless for pure Javascript).

Now, in putting this together, I'm trying to make my TypeScript definition consistent with both the specification text and the JSON Schema.  This is precisely why I prefer a Schema...because you can really validate against it.  In checking specification vs. schema, I've identified the following issues:

1. Specification text says that a Link requires a rel.  JSON Schema doesn't mark it as required.
2. Specification text says that a Link requires an href.  JSON Schema doesn't mark it as required.
3. Specification test says an Action requires an href.  JSON Schema only requires name as part of Action.

I think that is it.  Let me know if you see any issues.

P.S. - If the JSON Schema were in the repo, I could have sent this as a pull request... ;-)

--

Mike

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/CAGA7vN6HAyAJrcc28iFx4v6-j-Zh%2BXwz3%3Dynp%2BUFwTGfpob3gg%40mail.gmail.com.

[Eric Knutson]

We started out favouring full embedded entities. It reduced round trips and made initial loading of collections really efficient. This became more useful when the client could signal to the server that you want the entities 'hydrated' and embedded or not. (param like embedDepth=2 if you needed the subentities' subentities embedded )

We've been moving more and more in the direction of embedded links vs. full entities unless the client explicitly requests them be embedded. It does make for really quick responses when you can just format the URI instead of getting the data, but it also allows for clients that cache to not be penalized with data they already have; They only fetch resources they've not seen. With HTTP/2 as possibility, the dreaded N + 1 is also somewhat mitigated

When we first started using Siren, I felt this embedded links were kind of a useless option, but having it as an option to embed or just link turned out to be super powerful for performance tuning

[ShaunP]

We are consuming our Siren API's with Ember Data.  

We have found that embedded links are preferable for lazy-loading as quite often we just want the properties back from a resource and don't want to bloat the payload with all the entities.  

As an example, we have one of our resources is a menu with entities of all the recipe items for that menu.  Most often we just want to pull up summary information for the menu so that we can see number of covers taken, gross profit margins per day etc.  Only on a couple of screens do we drill down and view all the recipes for the menu.

[Michael Tiller]

But to me the real question here is why have embedded link sub-entities at all.  As far as I can tell, a link and an embedded link sub-entity have exactly the sample fields: class, rel, href, type and title.

Note that the specification says these are "different" because one is for relationships between entities and the other is for referencing things "outside the graph".  But I'm not sure whether that distinction merits the complexity of the specification and the implementation.  I've been working quite a bit with Siren in the last year and I find the need to, at runtime, examine each item in "entities" to see if it is an embedded representation or just a link to be annoying.  So that is what I mean by implementation complexity.

It seems to me that the issue (if I understand it) in this distinction is related to how loosely things are related.  For example, if I have a collection resource, any "items" (in the IANA Link Relations sense) are tightly coupled to my resource.  On the other hand, I might have other relations like links to web sites that are just saying "here is something related somehow, but it doesn't really belong to me...".

But I think you should just have a convention within your application to identify those "loose" relations.  Just use (IANA) "related" or something with hardly any semantic meaning if you want to loosely couple.  I think this would make the specification much cleaner because having two types of constructs with the same underlying data model seems pretty confusing to me.

--

Mike

--
You received this message because you are subscribed to the Google Groups "Siren Hypermedia" group.

To unsubscribe from this group and stop receiving emails from it, send an email to siren-hypermedia+unsubscribe@googlegroups.com.
To post to this group, send email to siren-hypermedia@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/d903ec6b-25b6-4457-b5a9-0cc202b538f2%40googlegroups.com.