BABL

BABL (Bannerman API Builder Language) is a templating langage for generating JSON in APIs.

It plays a role similar to RABL, JBuilder, Grape Entity, and many others. However, unlike existing tools, BABL has several advantages :

Static compilation

BABL is a simple Ruby DSL. Unlike RABL, the template code is fully parsed and executed before any data is available. The approach makes it possible to detect errors earlier and document the output schema automatically, without data.

Automatic preloading

BABL is also able to infer the "input schema". It can loosely be seen as the list of properties we need to read from the models to construct the JSON output. These dependencies can be used to retrieve data more efficiently. For instance,all ActiveRecord associations can be preloaded automatically using this mechanism.

Simple syntax

JSON is simple, and generating JSON should be as simple as possible.

BABL template:

object(
    document: object(
        :id, :title

        owner: _.nullable.object(:id, :name),
        authors: _.each.object(:id, :name),
        category: 'Not implemented'
    )
)

Output:

{
    "document": {
        "id": 1,
        "title": "Hello BABL",
        "owner": null,
        "authors": [
            { "id": 4, "name": "Fred" },
            { "id": 5, "name": "Vivien" }
        ],
        "category": "not implemented"
    }
}

Documentation

TODO

Current limitations

Automatic preloading

This feature only works if BABL is configured to use an external preloader.

As of today, the only compatible preloader implementation has not been released yet. Hopefully, it will be available soon :-)

Automatic documentation

Support for automatic documentation is very limited, and the output is indecently ugly. It is more a proof-of-concept that a useful feature.

The mid-term goal is to generate a JSON schema documentation.

Rails integration

This gem implements support of *.babl views in Rails.

In theory, the template could be compliled once for all and re-used for subsequent requests. In practice, today's implementation will re-compile the template at every request, because Rails templating mechanism doesn't make our life easy.

If it turns out to be a performance bottleneck, we will try to work around this issue.

Recursion

BABL does not support recursive templates. The first reason is that it makes dependency tracking more complicated (especially on preloader side). The other reason is that it is not as useful as it might seem.

License

Licensed under the MIT license.