yaks 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 44bddcd54510d2f8a9fbd3a928874218eb12f946
-  data.tar.gz: 3d6578acf4bb8b7bb22e6b81e84e747321b6a456
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTZhMTliZGU4NTNkZTNmYjYyOGRhYzFjZjAwNTIwYTI4YTdjNDJjNA==
+  data.tar.gz: !binary |-
+    MmVjN2NjZDI0ZDhjNjliYTczZjk3ODE0OTJmNGQzNDk3ZmE3ZDk0OQ==
 SHA512:
-  metadata.gz: 48980782c7367fef882d2bc46cde48df3d13280fd19e196246461c774e7f81f2d300800a3c3f7c6f1560fd0ecf8b60afc9628f787110768f372b7c250766269d
-  data.tar.gz: 9733522792a868b261d48e429db1416104b62b2b8c80689a33b9c8dc8ede9d70d5173f16cded562b01adfa7aa5827cb0e59b1fac84ed0722538f9c409470420e
+  metadata.gz: !binary |-
+    M2E1ZWY2MzIyMzkyMmIxMDM3ZTFhZGRkODhhNzhiMjM1NTZiMTkxMDVjZjE2
+    MTc5NTAwYWI4NGJiOWJjMjVkNGI5MjdmZmM3OWE3ODIwYWYwMDNmM2FkNGMy
+    ZTcxNTRkNGIzMjgxZWU4OTdlYzMyMmUwYmEwYjRlM2FhODA1YTc=
+  data.tar.gz: !binary |-
+    NjJhM2ExODNhNGM2OTAzMzMzZDc3MjlkNTM0NWVmM2I1N2VlMjdkZmYxZWU2
+    Mzg2MmQxZmYyNmZkZTJjODZlMDFiYjViZjA5OGVjMjI3ZDEyYzI3ZGEwZWUw
+    MDc3NWU0MDBiYTk5OWQ3ZGU3OTJkMTVlMzQ1MmUwNjllM2ExZjU=

data/.gitignore

@@ -1 +1,2 @@
 .bundle
+coverage

data/.travis.yml

@@ -0,0 +1,23 @@
+language: ruby
+before_install: gem install bundler
+bundler_args: --without yard guard benchmarks
+script: "bundle exec rspec"
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - ruby-head
+  - rbx-19mode
+matrix:
+  include:
+    - rvm: jruby-19mode
+      env: JRUBY_OPTS="$JRUBY_OPTS --debug"
+    - rvm: jruby-head
+      env: JRUBY_OPTS="$JRUBY_OPTS --debug"
+notifications:
+  email:
+    recipients:
+      - arne@arnebrasseur.net
+    on_success: never
+    on_failure: change

data/Gemfile

@@ -2,4 +2,4 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'hamster', path: '/home/arne/github/hamster'
+gem 'hamster', github: 'harukizaemon/hamster'

data/Gemfile.lock

@@ -1,15 +1,17 @@
+GIT
+  remote: git://github.com/harukizaemon/hamster.git
+  revision: aaf874b20bd31c2d984ae131dbf58d9a9bc2b379
+  specs:
+    hamster (0.4.3)
+
 PATH
   remote: .
   specs:
-    yaks (0.0.0)
+    yaks (0.1.0)
       concord (~> 0.1.4)
       hamster (~> 0.4.3)
       inflection (~> 1.0.0)
-
-PATH
-  remote: /home/arne/github/hamster
-  specs:
-    hamster (0.4.3)
+      uri_template (~> 0.6.0)
 
 GEM
   remote: https://rubygems.org/
@@ -28,11 +30,23 @@ GEM
     concord (0.1.4)
       adamantium (~> 0.1)
       equalizer (~> 0.0.7)
+    coveralls (0.7.0)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
     descendants_tracker (0.0.3)
     diff-lcs (1.2.5)
+    docile (1.1.1)
     equalizer (0.0.8)
     ice_nine (0.10.0)
     inflection (1.0.0)
+    mime-types (2.0)
+    multi_json (1.8.2)
+    rake (10.1.1)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
     rspec (2.14.1)
       rspec-core (~> 2.14.0)
       rspec-expectations (~> 2.14.0)
@@ -41,8 +55,18 @@ GEM
     rspec-expectations (2.14.4)
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.14.4)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
+    thor (0.18.1)
     thread_safe (0.1.3)
       atomic
+    tins (0.13.1)
+    uri_template (0.6.0)
     virtus (1.0.0)
       axiom-types (~> 0.0.5)
       coercible (~> 0.2)
@@ -53,7 +77,9 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  coveralls
   hamster!
+  rake
   rspec
   virtus
   yaks!

data/README.md

@@ -1,105 +1,207 @@
-# Yankee Alpha Kilo Serializers
+[![Gem Version](https://badge.fury.io/rb/yaks.png)][gem]
+[![Build Status](https://secure.travis-ci.org/plexus/yaks.png?branch=master)][travis]
+[![Dependency Status](https://gemnasium.com/plexus/yaks.png)][gemnasium]
+[![Code Climate](https://codeclimate.com/github/plexus/yaks.png)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/plexus/yaks/badge.png?branch=master)][coveralls]
+
+[gem]: https://rubygems.org/gems/yaks
+[travis]: https://travis-ci.org/plexus/yaks
+[gemnasium]: https://gemnasium.com/plexus/yaks
+[codeclimate]: https://codeclimate.com/github/plexus/yaks
+[coveralls]: https://coveralls.io/r/plexus/yaks
+
+# Yaks
+
+### One Stop Hypermedia Shopping ###
+
+Yaks is a tool for turning your domain models into Hypermedia resources.
+
+There are at the moment a number of competing media types for building Hypermedia APIs. These all add a layer of semantics on top of a low level serialization format such as JSON or XML. Even though they each have their own design goals, the core features mostly overlap. They typically provide a way to represent resources (entities), and resource collections, consisting of
+
+* Data in key-value format, possibly with composite values
+* Embedded resources
+* Links to related resources
+* Outbound links that have a specific relation to the resource
+
+They might also contain extra control data to specify possible future interactions, not unlike HTML forms.
+
+These different media types for Hypermedia clients and servers base themselves on the same set of internet standards, such as [RFC4288 Media types](http://tools.ietf.org/html/rfc4288), [RFC5988 Web Linking](http://tools.ietf.org/html/rfc5988), [RFC6906 The "profile" link relation](http://tools.ietf.org/search/rfc6906) and [RFC6570 URI Templates](http://tools.ietf.org/html/rfc6570).
+
+## Yaks Resources
+
+At the core of Yaks is the concept of a Resource, consisting of key-value attributes, RFC5988 style links, and embedded sub-resources.
+
+To build an API you create 'mappers' that turn your domain models into resources. Then you pick a media type 'serializer', which can turn the resource into a hypermedia message.
+
+The web linking standard which defines link relations like 'self', 'next' or 'alternate' is embraced as far as practically possible, for instance to find the URI that uniquely defines a resource, we look at the 'self' link. To distinguish different types of resources we use the 'profile' link.
+
+## Mappers
+
+To turn your domain models into resources, you define mappers, for example :
 
 ```ruby
-class ShowSerializer < Yaks::Serialize
-  attributes :id, :name, :description, :dates
+class PostMapper < Yaks::Mapper
+  link :self, '/api/posts/{id}'
+
+  attributes :id, :title
+
+  has_one :author
+  has_many :comments
+end
+```
+
+Now you can use this to create a Resource
 
-  has_many :events
-  has_one :event_category
+```ruby
+resource = PostMapper.new(post).to_resource
+```
 
-  def description
-    object.description(:long)
+### Attributes
+
+Use the `attributes` DSL method to specify which attributes of your model you want to expose, as in the example above. You can override the `load_attribute` method to change how attributes are fetched from the model.
+
+For example, if you are representing data that is stored in a Hash, you could do
+
+```ruby
+class PostHashMapper < Yaks::Mapper
+  attributes :id, :body
+
+  def load_attribute(name)
+    object[name]
   end
+end
+```
+
+The default implementation will first try to find a matching method for an attribute on the mapper itself, and will then fall back to calling the actual model. So you can add extra 'virtual' attributes like so :
+
+```ruby
+class CommentMapper < Yaks::Mapper
+  attributes :id, :body, :date
 
-  def dates
-    events.map(&:day)
+  def date
+    object.created_at.strftime("at %I:%M%p")
   end
 end
+```
+
+#### Filtering
+
+Implement `filter(attrs)` to filter out specific attributes, e.g. based on options.
 
-class EventSerializer < Yaks::Serializer
-  attributes :id, :name
+```ruby
+def filter(attrs)
+  attrs.reject{|attr| options[:exclude].include? attr
 end
+```
 
-class EventCategorySerializer < Yaks::Serializer
-  attributes :id, :name
+### Links
+
+You can specify link templates that will be expanded with model attributes. The link relation name should be a registered [IANA link relation](http://www.iana.org/assignments/link-relations/link-relations.xhtml) or a URL.
+
+```ruby
+class FooMapper < Yaks::Mapper
+  link :self, '/api/foo/{id}'
+  link 'http://api.foo.com/rels/comments', '/api/foo/{id}/comments'
 end
+```
+
+To prevent a link to be expanded, add `expand: false` as an option. Now the actual template will be rendered in the result, so clients can use it to generate links from.
 
-json = JSON.dump(
-  Yaks::Dumper.new(format: :json_api).dump('shows', Show.upcoming)
-)
+### Associations
+
+Use `has_one` for an association that returns a single object, or `has_many` for embedding a collection.
+
+Options
+
+* `:as` : use a different name for the association in the result
+* `:mapper` : Use a specific for each instance, will be derived from the class name if omitted (see Policy vs Configuration)
+* `:collection_mapper` : For mapping the collection as a whole, this defaults to Yaks::CollectionMapper, but you can subclass it for example to add links or attributes on the collection itself
+* `:policy` : supply an alternative Policy object
+
+## Serializers
+
+A resource can be turned in to a specific media type representation, for example [HAL](http://stateless.co/hal_specification.html) using a Serializer
+
+```ruby
+hal = Yaks::HalSerializer.new(resource).serialize
+puts JSON.dump(hal)
 ```
 
+This will give you back a composite types consisting of primitives that have a mapping to JSON, so you can use your favorite JSON encoder to turn this into a character stream.
+
+### Yaks::HalSerializer
+
+Serializes to HAL. In HAL one decides when building an API which links can only be singular (e.g. self), and which are always represented as an array. So the HalSerializer understand the `:singular_links` option.
+
+```ruby
+hal = Yaks::HalSerializer.new(resource, singular_links: [:self, :"ea:find", :"ea:basket"])
+```
+
+CURIEs are not explicitly supported, but it's possible to use them with some effort, see `examples/hal01.rb` for an example.
+
+The line between a singular resource and a collection is fuzzy in HAL. To stick close to the spec you're best to create your own singular types that represent collections, rather than rendering a top level CollectionResource.
+
+### Yaks::JsonApiSerializer
+
+JSON-API has no concept of outbound links, so these will not be rendered, but the profile link information will be used to derive the root key.
+
+* `embed: :resources` : Embed resources in a `{"linked":` section, referenced by id
+* `embed: :links` : Use URL style JSON-API
+
+## Policy over Configuration
+
+It's an old adagio in the Ruby/Rails world to have "Convention over Configuration", mostly to derive values that were not given explicitly. Typically based on things having similar names and a 1-1 derivable relationship.
+
+This saves a lot of typing, but for the uninitiated it can also create confusion, the implicitness makes it hard to follow what's going on.
+
+What's worse, is that often the Configuration part is skimmed over, making it very hard to deviate from the Golden Standard.
+
+There is another old adagio, "Policy vs Mechanism". Implement the mechanisms, but don't dictate the policy.
+
+In Yaks whenever missing values need to be inferred, like finding an unspecified mapper for a relation, this is handled by a policy object. The default is `Yaks::DefaultPolicy`, you can go there to find all the rules of inference. Subclass it and override to fit your needs, then pass it in to each mapper/serializer, they will pass it on to whatever objects they call.
+
+```ruby
+PostMapper.new(post, policy: MyPolicy.new)
+```
+
+## ProfileRegistry , RelationRegistry
+
+...
+
+## Future plans
+
+* Collection+JSON
+* Siren
+* Examples on how to integrate with web frameworks
+
+## Acknowledgment
+
+The mapper syntax is largely borrowed from ActiveModel::Serializers, which in turn closely mimics the syntax of ActiveRecord models. It's a great concise syntax that still offers plenty of flexibility, so to not reinvent the wheel we stick to the existing syntax as far as practical, although there are several extensions and deviations.
+
+## How to contribute
+
+Run the tests, the examples, try it with your own stuff and leave your impressions in the issues. Or discuss on API-craft.
+
+To fix a bug
+
+1. Fork the repo
+2. Fix the bug, add tests for it
+3. Push it to a named branch
+4. Add a PR
+
+To add a feature
+
+1. Open an issue as soon as possible to gather feedback
+2. Same as above, fork, push to named branch, make a pull-request
+
 ## Non-Features
 
 * No core extensions
 * Minimal dependencies
 * Only serializes what explicitly has a Serializer, will never call to_json/as_json
 * Adding extra output formats does not require altering existing code
+* Has no opinion on what to use for final JSON encoding (json, multi_json, yajl, oj, etc.)
 
-## Formats
-
-* :json_api
-
-```json
-{
-   "shows" : [
-      {
-         "dates" : [ "next Sunday" ],
-         "name" : "Piglet gets his groove back",
-         "id" : 5,
-         "description" : "Once in a lifetime...",
-         "links" : {
-            "event_category" : 2,
-            "events" : [ 7 ]
-         }
-      }
-   ],
-   "linked" : {
-      "event_categories" : [
-         {
-            "name" : "Drama",
-            "id" : 2
-         }
-      ],
-      "events" : [
-         {
-            "name" : "Sneak preview",
-            "id" : 7
-         }
-      ]
-   }
-}
-```
-
-* :ams_compat
-
-```json
-{
-   "shows" : [
-      {
-         "dates" : [ "next Sunday" ],
-         "name" : "Piglet gets his groove back",
-         "id" : 5,
-         "description" : null,
-         "event_ids" : [ 7 ],
-         "event_category_id" : 2
-      }
-   ],
-   "event_categories" : [{
-         "name" : "Drama",
-         "id" : 2
-   }],
-   "events" : [{
-         "Name" : "Sneak preview",
-         "id" : 7
-   }]
-}
-
-## Maturity
-
-Infantile. Crazy what these kids get up to, though.
-
-requires current master of Hamster.
 
 ## License
 

data/examples/hal01.rb

@@ -0,0 +1,126 @@
+# http://stateless.co/hal_specification.html
+
+# There are still some affordances missing to support all of HAL, in particular
+# for this example to ability to generate links based on composite content
+# (ea:admin) is not implemented, neither is explicit support for CURIEs (compact
+# URI shorthand syntax), although this examples works around that by manually
+# encoding the CURIE prefixes.
+
+# The 'next' link from the example below is also ommitted, pagination is an aspect
+# that will be implemented generically
+
+# Example from the specification, approximated with Yaks below
+
+# {
+#     "_links": {
+#         "self": { "href": "/orders" },
+#         "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }],
+#         "next": { "href": "/orders?page=2" },
+#         "ea:find": { "href": "/orders{?id}", "templated": true },
+#         "ea:admin": [{
+#             "href": "/admins/2",
+#             "title": "Fred"
+#         }, {
+#             "href": "/admins/5",
+#             "title": "Kate"
+#         }]
+#     },
+#     "currentlyProcessing": 14,
+#     "shippedToday": 20,
+#     "_embedded": {
+#         "ea:order": [{
+#             "_links": {
+#                 "self": { "href": "/orders/123" },
+#                 "ea:basket": { "href": "/baskets/98712" },
+#                 "ea:customer": { "href": "/customers/7809" }
+#             },
+#             "total": 30.00,
+#             "currency": "USD",
+#             "status": "shipped"
+#         }, {
+#             "_links": {
+#                 "self": { "href": "/orders/124" },
+#                 "ea:basket": { "href": "/baskets/97213" },
+#                 "ea:customer": { "href": "/customers/12369" }
+#             },
+#             "total": 20.00,
+#             "currency": "USD",
+#             "status": "processing"
+#         }]
+#     }
+# }
+
+require 'virtus'
+require 'yaks'
+require 'json'
+
+class Order
+  include Virtus.model
+  attribute :id, Integer
+  attribute :basket_id, Integer
+  attribute :customer_id, Integer
+  attribute :total, Numeric
+  attribute :currency, String
+  attribute :status, String
+end
+
+class OrderSet
+  include Virtus.model
+  attribute :currently_processing, Integer
+  attribute :shipped_today, Integer
+  attribute :orders, Array[Order]
+end
+
+class OrderMapper < Yaks::Mapper
+  link :self, '/orders/{id}'
+  link :"ea:basket", '/baskets/{basket_id}'
+  link :"ea:customer", '/customers/{customer_id}'
+
+  attributes :total, :currency, :status
+end
+
+class OrderSetMapper < Yaks::Mapper
+  link :self, '/orders'
+  link :curies, 'http://example.com/docs/rels/{rel}', name: "ea", expand: false
+  link :"ea:find", "/orders{?id}", expand: false
+
+  attributes :currentlyProcessing, :shippedToday
+
+  has_many :orders, as: :"ea:order", mapper: OrderMapper
+
+  # Having the attributes be encoded in CamelCase is such a common
+  # use case we might have to make this a setting
+
+  def load_attribute(name)
+    super(Yaks::Util.underscore(name.to_s))
+  end
+end
+
+order_set = OrderSet.new(
+  currently_processing: 14,
+  shipped_today: 20,
+  orders: [
+    Order.new(
+      id: 123,
+      basket_id: 98712,
+      customer_id: 7809,
+      total: 30.00,
+      currency: "USD",
+      status: "shipped"
+    ),
+    Order.new(
+      id: 124,
+      basket_id: 97213,
+      customer_id: 12369,
+      total: 20.00,
+      currency: "USD",
+      status: "processing"
+    )
+  ]
+)
+
+resource = OrderSetMapper.new(order_set).to_resource
+
+hal = Yaks::HalSerializer.new(resource, singular_links: [:self, :"ea:find", :"ea:basket", :"ea:customer"]).to_hal
+
+puts JSON.dump(hal)