RC2: Resource Relationships

[csantero]

https://github.com/dgeb/json-api/blob/v1rc2/format/index.md#resource-relationships-

Self key

The spec does not require a self key on the links hash. Not sure if we want to support that immediately. But we do have to throw an error or transform relationship property names that would serialize as self.

SerializeAsAttribute

We have to rethink this attribute. The options the spec offers for serializing relationships are:

1. Serialize a string containing the related resource URL.
2. Serialize an object with the relationship URL keyed at self. I just commented for clarification on the rc2 PR, but I am pretty sure this URL alone is not sufficient.
3. Serialize an object with the related resource URL keyed at resource. This is functionally equivalent to An unexpected property name causes an infinite loop on deserialization #1, but more verbose.
4. Serialize an object with linkage to other resources, using type and id or ids. If this option is chosen the linked attributes must be included in the top level linked object, unlike in the past where you could send the related resource's ID but not make a compound document.
5. Serialize some combination of the above.

The main choice the developer has is:

1. Do I want to just send a resource URL?
2. Or should I link to a secondary resource in the compound document?

And of course like we discussed in #27, they might want to make this decision at runtime.

LinkTemplate

This attribute is still useful, since the spec only recommends a format for resource URLs, and the user might need to override that convention. It might make more sense to call it something like: ResourceUrlFormatAttribute. We would also need a way to override the default relationship URL.