kevinswiber/siren — pull request #31 by uglymunky (2014-02-19 00:12:43+00:00)
Title: Add name to embedded entities

Following up on [this thread](https://groups.google.com/forum/#!topic/siren-hypermedia/s3Ya8peQOfo)

Entities need a name, only then can you reference a particular entity. So long as entities do not have names, the only option we have for referencing a particular entity is by filtering. While filtering does produce a result, it will always return a set of results (either an empty set, a set of 1 or a set of greater than 1) when all we want is one.

On my Siren client, I've currently implemented a couple of workarounds for this:
1) add a non-standard "name" property to each entity
or
2) add a rel of "name:"

Ultimately, however, these are just workarounds for something that I believe belongs as part of the Siren spec.

I had considered getting rid of entities all together (and just having everything be a property) , however, I see how they are critical in order for clients to parse.

I had also considered just adding the name property but then felt awkward about veering too far away from the "standard entity".

So, while more verbose, it seemed best to wrap each sub-entity and add an optional "name" attribute there. Similarly pull the `href` and `rel` alttributes out into the wrapper so that the sub-entity does not get modified wether it is a sub-entity or the root entity:

```
entities: [
{name: 'items', href: 'api.io/order/1234/items', rel: 'some-rel', entity: {}}
{name: 'customer', rel: 'some-other-rel', entity: {}}
]
```

Sample user-case
I want to be able to do user->purchases or user->address. While I believe that the semantics are something that get set up by a Siren client, a Siren client can only achieve this if the underlying Siren spec provides for an entity to have a name.

(Apologies for the funky commit history, clearly I did something git funkiness)