JSON Schema Baby

Building an application programming interface is not easy. Designing an API is more complex than just writing code. For a few projects we tried out different approaches to implement an API in Ruby on Rails. There are two main ways to make your resources accessible:

• using the standard to_json renderer built into Rails
• building your own views

Using standard renderer provided by Rails

In Rails 2.0 you have the possibility to using the respond_to block to expose your resource in whatever format you rewuire (xml, json, html). E.g.:

The same is possible in Rails 3.0 but a little bit easier:

In these examples you can define the representation of your resource by defining the format you want the resource to be represented in. But in most cases you don’t want to expose every attribute of your resource. To achieve this, you could use Rails’ as_json method to create a custom JSON structure of your resource. E.g:

As Jonathan Julian mentioned in his blog post, call as_json directly or override it in your model to customize your representation of your resource. Sounds easy so far. Summarizing this approach we can say:

1. It is understandable and quite easy to use
2. You can easily customize the representation of your resources via the as_json method

But the way how this approach is realized is not the best in my opinion, because it too much correlated with the models when we talking only about a “representation”. That’s why I like the second approch – building your own views.

Customize it baby

What does it exactly mean? Instead of just overriding the as_json method in your model, build a template that exposes your API. The easiest way is, e.g., to use RABL – Ruby API Templating Language.

As in the example before you define within your controller structure WHICH resources are being exposed, like:

And within your RABL-Template now you can define HOW your resources should look:

What happened here is that the representation of the resource is properly split from the resource using templates, like using .html-templates that belongs to your views. Thats great. You’re very flexible to define how the respresentation should looks like without overriding some methods. The resource is exposed ‘as it is’ but the template takes the response of what representation exactly the API users should get. In general, that seems to be the right approach; and it really is, but for me it isn’t going far enough. What I like to see is an even looser representation.

Here comes JSON-Schema

Now we’re going a step further and completely split our resource from the representation. Based on JSON-Schema (http://json-schema.org/) we’re going to define one that is responsible how our resource is being represented. With this approach, it is also possible to define our yourself in which way you want to interpret the schema within your code. And it’s fully decorrelated if you want to.

If found a very good approach for using the JSON-Schema for an API representation (sk_api_schema – https://github.com/salesking/sk_api_schema) – a Ruby library that defines the schema which takes care of the representation of their API resources.

How does it work? Your controllers are almost the same. E.g.:

The only small difference is the object_as_json method, which is provided by your own schema library. This method takes the properties defined in the schema and looks them up on the object in question.

Within your schema for a single resource looks like this:

As you can see, the schema described everything:

• The resource itself – here a user
• Its properties – the attributes of this resource
• Links belonging to this resource – These describe some nested resources which belong to this resource and you can also define search parameters here

And there’s even one more big advantage: publishing your JSON-Schema library gives your API users a good and clean documentation of your interface. You don’t have to describe it anymore. Moreover, it could be possible to generate a nicer representation from your documentation. You can see an example of thishere: http://sk-api-browser.heroku.com/. This API browser reads the JSON-Schema here and generates a nice overview of the API.

Summary

What I tried to describe here were some facts about how to implement an API with Ruby on Rails but more about how to split the resource itself from the representation in your webservice. For this you can use internal methods responsible for representing your resource, or create your own templates with defined libraries like RABL. Using JSON schema for the representation of your API is the most loosely coupled approach. With JSON schema you’re don’t care about the resource’s representation within your code but reather within your schema. It’s a description of whatever you want to expose to your clients.

Resources

• A JSON schema browser
• SalesKing API schema
• JSON schema
• Set up RABL for Ruby on Rails
• Using RABL in Rails JSON Web API
• RABL
• RABL, The Ruby API Templating Language
• Rails to_json or as_json?

Comments