Developing your JSON API in Rails with Rabl
This post about building a simple API is only for fetching data, not persisting. And I’ll not mention REST here.
The Rabl gem let’s you easily make data available as JSON, using this gem is a real straightforward process. All you need to do is pass respond_to :json in the controller of the resource you wanna set available as JSON.
class CitiesController < ApplicationController respond_to :html, :json def index @cities = City.all end #... end
Now you have to create the template that determines how the JSON objects will be displayed, the file name follows the Rails convention having the name of it’s equivalent controller action and ends in .rabl:
# index.json.rabl collection @cities attributes :name, :population, :flag, :climate, :area child :city_hall do attributes :id, :name, :region, :location end child :neighborhoods do attributes :id, :name, :area, :population end child :inhabitants => :people do attributes :id, :name, :age, :profile_picture_url end child :major do attributes :id, :name, :mandate_start_date, :mandate_finish_date end
Explaining what happens in this file:
- The collection method takes the instance variable containing the objects you want to display, in my example, @cities
- The attributes method is for specifing which attributes of your model you want in the JSON output (you seldom wanna show all)
- The child method takes a block for a collection or a single object you want to nest to the parent object.
Explaining it better:
When I pass :major to the child method, Rabl expects in City a has_one associaton to the Major model. Equally, Rabl expects has_many :inhabitants to be present in the City model.
The coolest stuff is that all these related data gets nested just right in the output. Neat and pretty.
Now go get it!
$ curl -X GET http://localhost:3000/cities.json
Now you have the JSON of your dreams, totally valid, semantic and formatted.
More documentation on Rabl can be found at the gem’s README and Wiki on GitHub.
Rabl is very robust. If JSON is the problem, this gem solves it. Of course what I showed here is just a small part of what Rabl lets you do and I hope this blog post helps you out when you need to develop your own API. If you have something to add please leave it in the comments.
Rodrigo Alves is a 19 year-old hacker from Paulista, Brazil. He studies Computer Science at UFPE. Read more about him.