JsonSerializer
TODO: Write a gem description
Installation
Add this line to your application's Gemfile:
gem 'json_serializer'
And then execute:
$ bundle
Or install it yourself as:
$ gem install json_serializer
Usage
The gem offers two primary features, serialize ActiveRecord models and collections into JSON and providing JSON Output helpers for an API.
ActiveRecord Patch and Custom API Attributes
We patch ActiveRecord::Base and Array with a serializer method. You can simple call .serialize
to see this in action. If you want to customize the attributes that are serialized, simple add an api_attributes
method to your model:
class Post < ActiveRecord::Base
...
def api_attributes
{
id: self.id.to_s,
title: self.title.to_s,
body: self.body.to_s,
created_at: self.created_at.to_s,
author: self.user.api_attributes,
}
end
...
end
Adding the api_attributes
method will allow you to control and customize the out attributes. Also note that you can have associated models, in this case Author attribute is an associated model User. We'll need to add the api_attributes
to that model also.
JSON Output Helper
After you have setup your custom API attributes, you can easily output JSON with a few helper methods:
JSON Model
Output a model in JSON:
post = Post.find(params[:id])
json_model :accepted, post
It's that simple. This will automatically serialize and output your model as JSON. Notice the :accepted
attribute, this will set the Header Status Code to 202. You can always modify this, take a look at (this nice list of Rails HTTP Status Codes)[http://www.codyfauser.com/2008/7/4/rails-http-status-code-to-symbol-mapping] for more details.
You can optionally pass parameters by simple adding them to your json_model
method:
post = Post.find(params[:id])
json_model :accepted, post, param: "Some extra parameters", more: "And some more..."
You can also append full serialized objects:
post = Post.find(params[:id]) json_model :accepted, post, comments: post.comments.serialize
In this case we called post.comments.serialize
, which will actually collect all the objects in the array or ActiveRecord collection and serialize each one based on the API Attributes (if available) or just to_json.
JSON Models
Similar to the json_model method, there is a json_models method. This is simple:
posts = Posts.all
json_models :accepted, posts
Similarly, you can append additional parameters:
posts = Posts.all
json_models :accepted, posts, categories: Category.all.serialize, tags: Tag.all.serialize
Success and Error
You can create simple success and errors with a few helps. To create a successful JSON response, simple call:
# json_success message, hash={}
json_success "Great success!", extra_params: hash
# => { success: "true", message: "message...", ... additional params ... }
This will automatically send a 200 Ok response in the Header Status Code.
Error codes are similar:
# json_error code, message, metadata={}
json_error 404, "Post not found.", errors: "Whatever extra metadata and params"
# => { error: { message: "Message goes here", code: 404, meta_data: "goes here..." } }
And this will automatically add your status code to the HTTP response
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request