Feature Request: API Versioning

[coneybeare]

It would be great to add versioning to the gem… something like

api_accessible { :v1 => {:firstname, :lastname, :age},
                 :v2 => {:middlename, :lastname, :sex} }

and so on

[fabrik42]

hey,
I like this idea. But I think it should only take one version as default.
Maybe we could kill two birds with one stone and also allow different renderings of a model in general:

api_accessible, :v1, {:firstname, :lastname, :age}
api_accessible, :v2, {:middlename, :lastname, :sex}
api_accessible, :compact, {:middlename, :lastname}

Which could become in the controller:

render_for_api(:v2)

or

render_for_api_v2

This would also fit my actual needs...

[fabrik42]

FYI: I'm currently implementing this. It will work like that:

api_accessible, :v1, :firstname, :lastname, :age
api_accessible, :v2, :firstname, :lastname, :sex

Which can be used in the controller:

  render_for_api :v1, :xml  => @person

This does not only allow versioning but also to have multiple API representations of the model:

api_accessible, :public, :nick, :age
api_accessible, :private, :firstname, :lastname, :nick, :age

Any feedback is welcome!
I will test it and propably push it tomorrow. :)

[coneybeare]

I think that for user syntax and readbility, the call should look something like:

api_accessible :v1, { :firstname, :lastname, :age }

or

api_accessible :v1 => { :firstname, :lastname, :age }

currently, you have a comma after the api_accessible and the arg dictionary can be mandatory if you would like, instead of the open dictionary. The idea of multiple api representations is excellent and the standard syntax is great, i just think the syntax for the api specific versions can be more readable in order to evade any confusion

[fabrik42]

you're right. it is a bit confusing, but your examples won't work, because you have to be able to pass symbols as well as hashes.
but something like this would work:

api_accessible :v1 => [ :firstname, :lastname, :age,  { :avatars => :all_avatar_sizes } ]

I think this looks already better than my last suggestion.

edit: I think you have to use the curly brackets now for passing hashes, else it's not syntactically correct.

[coneybeare]

I agree. It also frees up the user to use a database column "v1"

[fabrik42]

yep - you don't need that. in fact you can use a simple controller method to access the right representation.

api_accessible, :v1_private, :firstname, :lastname, :age
api_accessible, :v2_private, :firstname, :lastname, :age, :sex
api_accessible, :v1_public, :nickname
api_accessible, :v2_public, :nickname, :sex

Then you could do something like this in the controllers:

def api_template( template = :public )
    "#{@api_version}_{template.to_s}".to_sym
end

render_for_api api_template(:private), :xml  => @person

That's what I was thinking of... Because you can basically set the API version wherever you like.

[coneybeare]

good idea

[fabrik42]

should work with the 0.2.1 gem version again! please note that you have to update your code, because you have to mention an api template now!