triAGENS/guacamole — pull request #83 by railsbros-dirk (2014-09-24 15:40:01+00:00)
Title: Implement relations between models as edges in a graph

**Note** This issue will close the discussion from #74 and marks the actual start of the implementation.

Since we added support for the [new Graph-Module](http://docs.arangodb.org/General-Graphs/README.html) in Ashikawa::Core we want to implement relations in Guacamole as Edges between Documents. With this change we will **deprecate the current implementation using foreign keys**. The implementation build upon a graph will result in a new API for defining relations.

There are some implications resulting from this approach:

* There will be always a Graph when using Guacamole
* All Collections will be added to this Graph (at least as orphans)

Furthermore we will model the edges explicitly (and only explicitly, at least for now). We think this is the right approach since we eventually want to allow explicit modeling of the edges anyhow.

The current API proposal for these new relations is as follows:

```ruby
class Post
attribute :author
end

class PostsCollection
maps do
# Will realize a connection between Post and User as Authorship-Edges
attribute :author, via: Authorship
end
end

class User
attribute :posts, Array[Post]
# Optionally you can make the Edge(s) accessible from the model
attribute :authorship, Authorship
end

class UsersCollection
maps do
attribute :posts, via: Authorship
end
end

# A explicit edge class
class Authorship
include Guacamole::Edge

# Define the _from / _to attributes of the edge
from UsersCollection, as: :author # optionally create an alias for those attribute getters
to PostsCollection, as: :of
end
```

Under the hood will happen the following:

* Create a graph
* Create both a `posts` and `users` vertex collection inside that graph
* Create an edge definition for that graph named `authorship` and `from` set to `users` and `to` set to `posts`
* Add edges to the `authorship` edge collection as appropriate
* Get the related user/post objects via a neighbors function