Json Shema 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:
- It is understandable and quite easy to use
- 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
Machine Readable Documentation, eh?!
So you've read this post, yer? If not, just have a quick read through as it will give you the general overview of Arrrpi.
As Jan pointed out in that post; publishing your documentation in this way gives it a very basic structure that is easily readable by a machine.
To show the power of this I have started writing a library that will read a document and build you a fully working wrapper for the API that you describe.
I have re-written a very small part of the Twitter API using the microformats:
To run the generator, it's as simple as:
And now we have a working wrapper:
There's a lot that we have planned for the library, you can follow its progress over on Github.
I have also put the generated wrapper here as I plan to cover the whole of the Twitter API.
What is ARRRPI?
As I mentioned in my last post, our goal is to create a service that combines a few things together to make API-descriptions more usable.
Heres a general overview of the idea:
1. Publish and Read APIs
If you are an owner of a webservice and you have an API, you should have a description for that API. The point is, every service has its own description. So every RESTful API has the same structure: resources, methods, input and output-prameters. Think of Rdoc or Javadoc for your web service. Moreover all APIs are annotated with hRESTs-Microformat, thus its machine-readable. Users can read the API online or via RSS and be up-to-date about every change.
2. Pull APIs
Sometimes people say: "Why should I describe my API within a third party application - its too much overhead". The idea behind the pull-function is to pull existing APIs into ARRRPI, without the overhead of creating the API manually. It works like the Google Analytics Principle. The service owner will add some simple microformats into their API documentation, then ARRRPI can grab the API, with all its details.
3. Export APIs
As the API-description is microformatted, its easy to export the API-description in different formats, such as: HTML-Pages, PDF-Documents, etc.
Maybe the developer has no time to do this. So, ARRRPI provide a simple GUI to describe the API. Then the API-descriptions are microformatted automatically. Now it is possible to generate for example Ruby Gems or Symfony Plugins for this service, because in a RESTful manner every API looks the same.
4. Version APIs
An interesting discussion is the need of API versioning. Its such a large topic that I'll discuss this point in another post. I believe, without a doubt, there is a need for versioning, thus ARRRPI provides a simple Semantic Versioning support.
Every time the service owner creates or updates an API-description, he has to describe if it was a major/minor change, or a patch. After updating the description all subscribed users can get an E-Mail notification or a RSS update. So changes can be easily announced without any overhead (e.g. write them an E-Mail etc.). For critical business mashups this can be a huge improvement - after a notification the service can be easily updated. Owners of services can have as many APIs as they want - private and public ones.
5. "iLike" and comment APIs
Moreover ARRRPI provides a few community aspects. Users can "like" APIs on Facebook or other social networks. Users can also add comments, and service owners can comment in private, so user reviews and enhancement proposals of the community can be easily discussed within the development team. Also an interface to the search engine of Programmable Web is planed, so users can easily get access to the broader community of the given API of a service.
6. Tooling & Debugging
Tooling & Debugging is also an aspect we are discussing. Some great examples of these include are Apigee or hurl.it. The goal is to give the user an integrated interface to debug and test the apis services before using them; this saves time within the development process and allows users to easily experiment with different API's.
We're developing our first prototype and want to publish it shortly. If you're interessted to test the pre-release of ARRRPi in a few weeks, just hit us an E-Mail to: arrrpi@railslove.com
