locks/halibut — pull request #11 by jesjos (2014-08-22 13:28:10+00:00)
Title: Single object relations

# Main idea and rationale

This PR mainly deals with single object relations, and the means to correctly preserve them when serializing or deserializing HAL documents.

As far as I can see, correctness stands against ease of use. As we know, the spec states that relations can be either single objects or arrays of objects. Ideally, we would like to be able to deserialize a HAL doc and get the exact same JSON representation back when serializing it. In that sense, returning a single object when that is indeed the nature of the relation would be more correct. But in practice this makes for a cumbersome API – we want to always return an Array (or nil).
The existing solution for discriminating between single objects and arrays with one object in them wasn't complete, and I wasn't keen on having two separate methods and RelationMaps for adding objects to relations, depending on whether they are arrays.

So I made an attempt at eating the cake and keeping it too, by storing the relations with correctness in mind, but wrapping values in arrays when they are accessed.

## Other notes

PR contains breaking changes, in that `#add_embedded_resource` has been removed.

It also contains fixes the non-compliant key for the `curies` object and some spelling fixes.

It also contains changes to ResourceExtractor. It now consumes a Hash instead of a JSON string, which makes it easier to use in isolation.

I totally understand that my solution isn't perfect and that I did some invasive changes, but I hope this can at least serve as a basis for further discussions.