Added support for versionned JSON

[dblock]

Mongoid::CachedJson now supports JSON versionning with json_fields_for. The obvious use-case is to return different JSON versions from API v1 and API v2. For example, version 2 of Widget splits name into first and last.

class Widget
  include Mongoid::CachedJson

  field :first
  field :last

  json_fields_for :v1 \
    :name => { :definition => lambda { |instance| "#{instance.first} #{instance.last}" } }

  json_fields_for :v2 \
    :first => { },
    :last => { }

end

JSON fields declared with json_fields instead of json_fields_for are used for all versions.

[fancyremarker]

I like the structure above for declaring json_fields for different versions; I wonder whether others would prefer a single json_fields call where each definition could specify an (optional) :versions argument, a la

json_fields \
  :name => { :versions => [ :v1 ], :definition => lambda { |instance| "#{instance.first} #{instance.last}" } },
  :first => { :versions => [ :v2 ] },
  :last => { :versions => [ :v2 ] }

I suspect a majority would prefer what you already have, but might be worth a quick poll.

[fancyremarker]

"Versioning"

[dblock]

You're right, it's possible people will want a declaration where you say whether a field applies to this or that version. That would be pretty nightmarish to manage imo, because when you add :v3, you have to go back to all JSONs and add it into each declaration? Unless of course versions is a range, but that has some of its own disadvantages.

@aaw - thoughts?

[fancyremarker]

This looks great, and is a very useful feature. I would probably add a json_fields declaration in the JsonFoobar scaffold (or add a new one), so as to make sure that json_fields-declared fields still show up in all as_json versions even when multiple json_fields_for calls exist in the same class.

[fancyremarker]

This looks good, though, I'd say it's merge-able whenever you want.

[aaw]

I like Frank's idea - I think in most cases, the intersection between the field definitions in two different versions of an API will be large, and it's going to get unmanageable once you have several json_fields_for declarations in the same class.

We should support ranges of versions, but it doesn't need to be much more syntax than you have already - the common case is that you've added a new field in a new version, the not-so-common case is that you've removed a field in a new version, so maybe something like:

json_fields \
  :name => { :version => :v1, :definition => lambda { |instance| "#{instance.first} #{instance.last}" } },
  :first => { :version => :v2 },
  :middle => { },
  :last => { :version => :v2 , :deprecated_at => :v3 }

Which would mean that :name is in version 1 and above, :middle is in every version, :first is in version 2 and above, and :last was in version 2 and version 3 but not version 4 or above.

[dblock]

I am going to close this, reopened https://github.com/dblock/mongoid-cached-json/pull/3 with the inline version. I took most of the suggestions except the retiring part - I think it's pretty dangerous to assume that the version is something sortable and incrementable - I might want the :red version or the :blue version.