Sub-Entities vs Links

126 views

Skip to first unread message

Eric Knutson

unread,

Jun 30, 2016, 2:41:18 PM6/30/16

to Siren Hypermedia

The explanation in the spec is pretty clear when I read through it, but in implementation, it sometimes gets cloudy. I think I make it cloudy because I want to embed data as a sub-entity to save me a call from the client, and it doesn't

So an example might be if you were building a google groups clone, where you use and external identity provider to log in (FB, google, github etc.), but normalized into a Siren'ized model for consistency from another service you have, we'll call it https://users.example.com

It seems like there are 2 approaches here:

embed the user entity as a sub-entity of the reply and save the calling client a trip to the users service
point to the author using the link with the author rel in that they are a distinct entity on another domain, but related to this post in that the user from that domain did the action.

In my example, I've made dates a first-class entity instead a property for a couple reasons: They can have discrete actions on them and can have different relationships to the parent entity; a creation date is a different thing than a modification date, and different still than a modified date.

I also included dates to kind of emphasis the why including the user kinda felt wrong. There is nothing in Siren that precludes heterogeneous sets of subentities, but it feels like a post is associated with a user, where as it has dates that give specific information and context to the post itself

Example:

{
    "class": ["paged", "replies", "collection"],
    "properties": {
        "total": 100,
        "pageSize": 1
    },
    "entities": [{
        "class": ["reply"],
        "properties": {
            "message": "I love lamp"
        },
        "entities": [{
            "class": ["date"],
            "rel": ["https://chat.example.com/rels/date#created"],
            "properties":{
                "date": "2016-06-30T17:38:17.650Z"
            }
        }, {
            "class": ["date"],
            "rel": ["https://chat.example.com/rels/date#visible"],
            "properties": {
                "date": "2016-06-30:40:17.650Z"
            },
            "actions": [{
                "name": "remove-visibility-restriction",
                "method": "DELETE",
                "href": "https://chat.example.com/12318/replies/100/visibility"
            }, {
                "name": "update-visibility-restriction",
                "method": "PUT",
                "href": "https://chat.example.com/12318/replies/100/visibility",
                "fields": [{
                    "name": "date", "type": "datetime"
                }]
            }]
        }],
        "links": [{
            "rel": ["self"],
            "href": "https://chat.example.com/12318/replies/100"
        }, {
            "rel": ["author"],
            "href": "https://users.example.com/38283"
        }]
    }],
    "links": [{
        "rel": ["self"],
        "href": "https://chat.example.com/12318/replies?page=51"
    }, {
        "rel": ["prev"],
        "href": "https://chat.example.com/12318/replies?page=50"
    }, {
        "rel": ["up"],
        "href": "https://chat.example.com/12318"
    }]
}

From the spec: Another distinction is the difference between sub-entities and links. Sub-entities exist to communicate a relationship between entities, in context. Links are primarily navigational and communicate ways clients can navigate outside the entity graph.

Reading that makes me feel like the user entity really should be transcluded from the users domain into the subentities of the post because it does communicate a relationship, in that context.