cph/rabl-oldrabl 0.8.6 + corrección para CVE-2014-4671
RABL (Ruby API Builder Language) es un sistema de plantillas Ruby para Rails y Padrino que genera JSON, XML, MessagePack, PList y BSON. Al usar el método 'to_json' de ActiveRecord, me encuentro deseando una solución más expresiva y potente para generar APIs. Esto es especialmente cierto cuando la representación JSON es compleja o no coincide exactamente con el esquema definido en la base de datos.
En particular, quiero fácilmente:
Cualquiera que haya probado el método 'to_json' usado en ActiveRecord para generar una respuesta JSON ha sentido el dolor de este enfoque restrictivo. RABL es un sistema de plantillas general creado para resolver estos problemas abordando la generación de respuestas API de una manera completamente nueva.
En esencia, RABL se trata de adherirse a los principios MVC delegando las representaciones de datos de la API a la capa de vista de tu aplicación. Para un desglose de conceptos erróneos comunes sobre RABL, consulta nuestra guía para entender RABL que puede ayudar a aclarar cualquier confusión sobre este proyecto.
v0.8.0 (publicado el 14 de febrero de 2013) elimina la dependencia de multi_json y se basa en Oj (o JSON) como analizador JSON. Simplifica el código, elimina una dependencia pero es posible que desees eliminar cualquier referencia a MultiJson.
v0.6.14 (publicado el 28 de junio de 2012) requiere el uso de render_views con RSpec para probar las plantillas. De lo contrario, el controlador simplemente pasará el comando render como lo hace con las plantillas ERB.
Instala RABL como una gema:``` gem install rabl
o añádelo a tu Gemfile:```ruby
# Gemfile
gem 'rabl'
# Also add either `oj` or `yajl-ruby` as the JSON parser
gem 'oj'
y ejecuta bundle install para instalar la dependencia.
Si estás usando Rails 2.3.8 (y superiores), Rails 3.X o Padrino, RABL funciona sin configuración.
Importante: Con Padrino, asegúrate de que la gema rabl esté listada después de la gema padrino en tu Gemfile, de lo contrario Rabl no se registrará correctamente como un motor de plantillas.
Con Sinatra, o cualquier otro framework basado en tilt, simplemente registra:```ruby Rabl.register!
y RABL se inicializará y estará listo para usar. Para su uso con Sinatra, consulta la guía de [Uso de Sinatra](https://github.com/nesquena/rabl/wiki/Setup-for-Sinatra).
## Resumen ##
Puedes usar RABL para generar APIs basadas en JSON y XML desde cualquier objeto de Ruby. Con RABL, los datos generalmente se derivan principalmente de modelos (independientes del ORM) y la representación de la salida de la API se describe dentro de una plantilla de vista utilizando un DSL simple de Ruby. Esto te permite mantener tus datos separados del JSON o XML que deseas generar.
Una vez que hayas instalado RABL (explicado anteriormente), puedes construir una plantilla de vista de RABL y luego renderizarla desde tus aplicaciones Sinatra, Padrino o Rails desde el controlador (o ruta) muy fácilmente. Usando [Padrino](http://padrinorb.com) como ejemplo, suponiendo que tienes un modelo `Post` lleno de publicaciones de blog, puedes renderizar una representación de la API (tanto JSON como XML) creando una ruta:```ruby
# app/app.rb
get "/posts", :provides => [:json, :xml] do
@user = current_user
@posts = Post.order("id DESC")
render "posts/index"
end
Luego podemos crear la siguiente plantilla RABL para expresar la salida de la API de @posts:```ruby
collection @posts attributes :id, :title, :subject child(:user) { attributes :full_name } node(:read) { |post| post.read_by?(@user) }
Lo cual generaría el siguiente JSON o XML al visitar `http://localhost:3000/posts.json````js
[{ "post" :
{
"id" : 5, title: "...", subject: "...",
"user" : { full_name : "..." },
"read" : true
}
}]
Eso es una visión general básica, pero hay mucho más que ver, como partials, herencia, nodos personalizados, etc. Lee los detalles completos de RABL a continuación.
RABL está diseñado para requerir poca o ninguna configuración para funcionar. Este es el caso en la mayoría de los escenarios, pero dependiendo de tus necesidades, es posible que desees establecer las siguientes configuraciones globales en tu aplicación (este bloque es completamente opcional):```ruby
require 'rabl' Rabl.configure do |config|
end
Cada opción especifica un comportamiento relacionado con la salida de RABL. Si `include_json_root` está deshabilitado, se elimina el
nodo raíz para cada objeto raíz en la salida, y `enable_json_callbacks` habilita el soporte para la salida de estilo 'jsonp' callback
si la solicitud entrante tiene un parámetro 'callback'.
Si `include_child_root` se establece en `false`, los objetos hijo en la respuesta no incluirán
un nodo raíz por defecto. Esto permite afinar aún más la estructura de respuesta deseada.
Si `cache_engine` está configurado, debe asignarlo a una clase con un método `fetch`. Consulte el [motor predeterminado](https://github.com/nesquena/rabl/blob/master/lib/rabl/cache_engine.rb) para ver un ejemplo.
Si `perform_caching` se establece en `true`, entonces realizará el almacenamiento en caché. Puede
ignorar esta opción si está usando Rails, es equivalente a
`config.action_controller.perform_caching` de Rails.
Si `cache_sources` se establece en `true`, las búsquedas de plantillas se almacenarán en caché para mejorar el rendimiento.
La caché se puede restablecer manualmente ejecutando `Rabl.reset_source_cache!` dentro de su aplicación.
Si `cache_all_output` se establece en `true`, cada plantilla, incluyendo cada plantilla individual utilizada como parte de una colección, se almacenará en caché por separado.
Además, cualquier cosa dentro de child, glue y partial también se almacenará en caché por separado.
Para almacenar en caché solo una sola plantilla, consulte la sección titulada 'Caching' más abajo.
Si `escape_all_output` se establece en `true` y ActiveSupport está disponible, la salida de atributos se escapará usando [ERB::Util.html_escape](http://corelib.rubyonrails.org/classes/ERB/Util.html).
Los nodos personalizados no se escaparán, use `ERB::Util.h(value)`.
Si `view_paths` se establece en una ruta, esta ruta de vista se verificará para cada plantilla rabl dentro de su aplicación.
Agregue a esta ruta especialmente cuando incluya Rabl en un motor y use rutas de vista dentro de otra aplicación Rails.
Si `raise_on_missing_attribute` se establece en `true`, se lanzará un RuntimeError cada vez que Rabl
intente representar un atributo que no existe. De lo contrario, el atributo simplemente se omitirá.
Establecer esto en `true` durante el desarrollo puede ayudar a aumentar la robustez de su código, pero no se recomienda usar `true` en
código de producción.
Si `replace_nil_values_with_empty_strings` se establece en `true`, todos los valores que sean `nil` y que normalmente se mostrarían como `null` en la respuesta se convierten en cadenas vacías.
Si desea usar [oj](https://github.com/ohler55/oj) como
el motor de codificación JSON principal, simplemente agréguelo a su Gemfile:```ruby
# Gemfile
gem 'oj'
y RABL usará ese motor automáticamente para codificar tus respuestas JSON.
Configura tu propio json_engine personalizado que defina un método dump o encode
para convertir datos de Ruby a JSON:```ruby
config.json_engine = ActiveSupport::JSON
### Configuración de formato ###
RABL admite configuración para MessagePack, BSON y Plist. Consulte la página
[Configuración de formato](https://github.com/nesquena/rabl/wiki/Configuring-Formats) para más detalles.
## Uso ##
### Asignación de objetos ###
Para declarar el objeto de datos para usar en la plantilla:```ruby
# app/views/users/show.json.rabl
object @user
o especifica un alias para el objeto:```ruby object @user => :person
o pasar una colección de objetos:```ruby
collection @users
# => [ { "user" : { ... } } ]
o especifique una etiqueta de nodo raíz para la colección:```ruby collection @users => :people
o incluso especificar tanto las etiquetas secundarias como las raíz para una colección:```ruby
collection @users, :root => "people", :object_root => "user"
# => { "people" : [ { "user" : { ... } } ] }
y esto se usará como los datos predeterminados para el renderizado, o deshabilitar explícitamente la raíz del objeto:```ruby collection @users, :root => "people", :object_root => false
También puede haber casos extraños donde el nivel raíz de la respuesta no se asigna directamente a ningún objeto:```ruby
object false
node(:some_count) { |m| @user.posts.count }
child(@user) { attribute :name }
En esos casos, se puede asignar 'false' al objeto y los nodos se pueden construir de forma libre.
Uso básico del templater para definir algunos atributos simples para la respuesta:```ruby
attributes :id, :foo, :bar
o usar con atributos aliased:```ruby
# Take the value of model attribute `foo` and name the node `bar`
attribute :foo => :bar
# => { bar : 5 }
o incluso múltiples atributos con alias:```ruby attributes :bar => :baz, :dog => :animal
o mostrar atributos solo si una condición es verdadera:```ruby
# m is the object being rendered, also supports :unless
attributes :foo, :bar, :if => lambda { |m| m.condition? }
Los atributos nombrados y con alias no se pueden combinar en la misma línea. Esto actualmente no funciona:```ruby attributes :foo, :bar => :baz # throws exception
### Nodos Hijos ###
A menudo, una respuesta requiere incluir información anidada de datos asociados con el modelo padre:```ruby
child :address do
attributes :street, :city, :zip, :state
end
También puedes deshabilitar la raíz del objeto para el nodo hijo:```ruby child :posts, :object_root => false do attributes :id, :title end
También puedes añadir nodos hijos desde una fuente de datos arbitraria:```ruby
child @posts => :foobar do
attributes :id, :title
end
o utiliza asociaciones de modelos con un alias:```ruby
child :posts => :foobar do attributes :id, :title end
También puede pasar el objeto actual:```ruby
object @user
child :posts do |user|
attribute :title unless user.suspended?
end
También puedes añadir atributos hijos de vuelta al nodo raíz:```ruby
glue @post do attributes :id => :post_id, :name => :post_name end
Usa glue para agregar atributos adicionales al objeto padre.
También puedes pasar el objeto actual:```ruby
object @user
glue(@post) {|user| attribute :title if user.active? }
Esto generará una respuesta json basada en el resultado del bloque node:```ruby
node :full_name do |u| u.first_name + " " + u.last_name end
o un nodo personalizado que existe solo si una condición es verdadera:```ruby
# m is the object being rendered, also supports :unless
node(:foo, :if => lambda { |m| m.has_foo? }) do |m|
m.foo
end
o no pases un nombre y haz que el bloque de nodo se fusione en la respuesta:```ruby node do |u| { :full_name => u.first_name + " " + u.last_name }
end
### Partials ###
Puede utilizar nodos personalizados como estos para crear representaciones flexibles de un valor utilizando todos los datos del modelo.
A menudo necesita acceder a otros objetos de datos para construir nodos personalizados en asociaciones más complejas. Puede obtener acceso a la representación rabl de otro objeto de datos renderizando un parcial RABL:```ruby
node :location do
{ :city => @city, :address => partial("users/address", :object => @address) }
end
o incluso acceder a un objeto asociado con el modelo padre:```ruby node :location do |m| { :city => m.city, :address => partial("users/address", :object => m.address) } end
Puedes usar este método para construir nodos arbitrariamente complejos para tus APIs. Ten en cuenta que necesitas tener plantillas RABL definidas para cada uno de los objetos de los que desees construir representaciones de esta manera.
### Herencia ###
Otro problema común de muchos constructores de plantillas es la redundancia innecesaria de código. Típicamente, muchas representaciones de un objeto a través de múltiples endpoints comparten atributos o nodos comunes. Los nodos para un objeto 'post' son probablemente los mismos o similares en la mayoría de las referencias a través de los diversos endpoints.
RABL tiene la capacidad de extender otras plantillas rabl "base" y atributos adicionales:```ruby
# app/views/users/advanced.json.rabl
extends "users/base" # another RABL template in "app/views/users/base.json.rabl"
node :can_drink do |m|
m.age > 21
end
También puedes extender otras plantillas rabl mientras construyes child nodes para reducir duplicación:```ruby
child @address do extends "address/item" end
Utilizar parciales y herencia puede reducir significativamente la duplicación de código en tus plantillas.
Puedes ver más ejemplos en la [página wiki de Reutilización de Plantillas](https://github.com/nesquena/rabl/wiki/Reusing-templates).
### Pasando locales en parciales ###
Puedes pasar un conjunto arbitrario de locales al renderizar parciales o extender plantillas.
Por ejemplo, si queremos mostrar en `posts/:id.json` cualquier información sobre un post en particular y sus comentarios asociados,
pero en otros casos queremos ocultar esos comentarios. Podemos usar locales para hacer esto:```ruby
# app/views/posts/index.json.rabl
collection @posts
extends('posts/show', :locals => { :hide_comments => true })
# or using partial instead of extends
# node(false) { |post| partial('posts/show', :object => :post, :locals => { :hide_comments => true })}
y luego acceder a las variables locales en la subplantilla:```ruby
object @post
attributes :id, :title, :body, :created_at node(:comments) { |post| post.comments } unless locals[:hide_comments]
### Ámbito de la Plantilla ###
Esto puede ser útil como una herramienta avanzada al extender o renderizar parciales.
### Ámbito de la Plantilla ###
En RABL, tienes acceso a todo lo que necesitas para construir una respuesta de API. Cada plantilla de RABL tiene acceso completo a las variables de instancia del controlador, así como a todos los ayudantes de vista y URLs de enrutamiento.```ruby
# app/some/template.rabl
object @post
# Access instance variables
child(@user => :user) { ... }
# or Rails helpers
node(:formatted_body) { |post| simple_format(post.body) }
No debería haber problema en obtener los datos apropiados para construir una respuesta.
En las API, a menudo es necesario construir nodos de segundo o tercer nivel. Supongamos que tenemos un modelo 'quiz' que tiene muchas 'preguntas' y luego cada pregunta tiene muchas 'respuestas'. Podemos mostrar esta jerarquía en RABL con bastante facilidad:```ruby
object @quiz attribute :title child :questions do attribute :caption child :answers do # Use inheritance to reduce duplication extends "answers/item" end end
Esto mostrará el objeto quiz con preguntas y respuestas anidadas, como se esperaría de un nodo quiz, y preguntas y respuestas incrustadas.
Tenga en cuenta que RABL puede anidarse arbitrariamente en profundidad dentro de nodos secundarios para permitir que se definan estas representaciones.
### Almacenamiento en caché ###
RABL tiene soporte de almacenamiento en caché integrado para plantillas que aprovechan estrategias de almacenamiento en caché de fragmentos. Tenga en cuenta que el almacenamiento en caché actualmente **solo está disponible** para Rails, pero se planea soporte para otros frameworks en una versión futura. El uso más simple de almacenamiento en caché es:```ruby
# app/views/users/show.json.rabl
object @quiz
cache @quiz # key = rabl/quiz/[cache_key]
attribute :title
El almacenamiento en caché puede acelerar significativamente el renderizado de las plantillas RABL en producción y se recomienda encarecidamente cuando sea posible. Para obtener una visión más detallada sobre el almacenamiento en caché, consulte la guía Caching en la wiki.
Existen situaciones en las que una aplicación necesita renderizar plantillas RABL fuera de un contexto de vista tradicional. Por ejemplo, para renderizar RABL dentro de una tarea Rake o para crear cargas útiles de colas de mensajes. Para este caso, se puede usar Rabl.render como se muestra a continuación:```ruby
Rabl.render(object, template, :view_path => 'app/views', :format => :json) #=> "{...json...}"
Puedes usar métodos de conveniencia en `Rabl::Renderer` para renderizar los objetos también:```ruby
Rabl::Renderer.json(@post, 'posts/show')
Rabl::Renderer.xml(@post, 'posts/show')
Estos métodos permiten utilizar RABL para conversiones arbitrarias de un objeto a un formato deseado.```ruby Rabl::Renderer.new('posts/show', @post, :view_path => 'app/views', :format => 'hash').render
También puedes pasar otras variables de instancia para usar en tu plantilla como:```ruby
Rabl::Renderer.new('posts/show', @post, :locals => { :custom_title => "Hello world!" })
Luego, en tu plantilla, puedes usar @custom_title como:```
attribute :content
node(:title) { @custom_title }
### Encabezados de tipo de contenido ###
Actualmente en RABL, el tipo de contenido de tu respuesta no se establece automáticamente. Esto se debe a que RABL está pensado para funcionar con cualquier framework basado en Rack y ser lo más agnóstico posible respecto al formato. Consulta [este issue](https://github.com/nesquena/rabl/issues/185#issuecomment-4501232) para más detalles, y si tienes ideas o parches, por favor házmelo saber.
Mientras tanto, asegúrate de establecer los tipos de contenido adecuados si es necesario. Esto suele ser bastante sencillo tanto en Rails como en Padrino. Recomiendo un *before_filter* en ese controlador o especificarlo directamente en una acción.
## Recursos ##
Hay muchos recursos disponibles relacionados con RABL, incluyendo la [Wiki de RABL](https://github.com/nesquena/rabl/wiki), y muchos tutoriales y guías detallados a continuación. También puedes visitar el [Sitio de RABL](http://nesquena.github.com/rabl).
### Uso Avanzado ###
Enlaces a recursos para uso avanzado:
* [Manejando la complejidad con presentadores](https://github.com/nesquena/rabl/wiki/Managing-complexity-with-presenters)
* [Optimizaciones para producción](https://github.com/nesquena/rabl/wiki/Rabl-In-Production)
* [Integración con Grape](https://github.com/nesquena/rabl/wiki/Using-Rabl-with-Grape)
* [Renderizando JSON para una estructura de árbol usando RABL](https://github.com/nesquena/rabl/issues/70)
* [Layouts (erb, haml y rabl) en RABL](https://github.com/nesquena/rabl/wiki/Using-Layouts)
* [Integración con Backbone o Ember.js](https://github.com/nesquena/rabl/wiki/Backbone-Integration)
* [RABL con Rails Engines](https://github.com/nesquena/rabl/wiki/Setup-rabl-with-rails-engines)
¡Por favor, agrega tus propios usos y házmelo saber para que los añadamos aquí! También asegúrate de revisar la [Wiki de RABL](https://github.com/nesquena/rabl/wiki) para otros usos.
### Tutoriales ###
Los tutoriales siempre pueden ser útiles al comenzar:
* [Railscasts #322](http://railscasts.com/episodes/322-rabl) - Ryan Bates explica RABL
* [BackboneRails](http://www.backbonerails.com/) - Grandiosos screencasts de Brian Mann
* [Creando una API con RABL y Padrino](http://blog.crowdint.com/2012/10/22/rabl-with-padrino.html)
* http://blog.joshsoftware.com/2011/12/23/designing-rails-api-using-rabl-and-devise/
* http://engineering.gomiso.com/2011/06/27/building-a-platform-api-on-rails/
* http://blog.lawrencenorton.com/better-json-requests-with-rabl
* http://www.rodrigoalvesvieira.com/developing-json-api-rails-rabl/
* http://tech.favoritemedium.com/2011/06/using-rabl-in-rails-json-web-api.html
* http://seesparkbox.com/foundry/better_rails_apis_with_rabl
* http://blog.dcxn.com/2011/06/22/rails-json-templates-through-rabl
* http://teohm.github.com/blog/2011/05/31/using-rabl-in-rails-json-web-api
Házmelo saber si hay algún otro recurso útil no listado aquí.
### Librerías Relacionadas ###
Hay otras librerías que pueden complementar o extender la funcionalidad de RABL:
* [versioncake](https://github.com/bwillis/versioncake) - Excelente librería para versionar fácilmente tus APIs de RABL
* [gon](https://github.com/gazay/gon) - Expone tus variables de Rails en JS con soporte integrado para RABL.
* [rabl-rails](https://github.com/ccocchi/rabl-rails) - Reimplementación de RABL para Rails [centrada en la velocidad](https://github.com/ccocchi/rabl-benchmark/blob/master/BENCHMARK).
Házmelo saber si hay alguna otra librería relacionada no listada aquí.
### Solución de Problemas ###
* [Llamadas redundantes para una colección](https://github.com/nesquena/rabl/issues/142#issuecomment-2969107)
* [Probando Vistas de RABL](https://github.com/nesquena/rabl/issues/130#issuecomment-4179285)
### Ejemplos ###
Consulta el directorio [examples](https://github.com/nesquena/rabl/tree/master/examples).
## Issues ##
Revisa la pestaña [Issues](https://github.com/nesquena/rabl/issues) para una lista completa:
* Evaluación comparativa rigurosa y optimizaciones de rendimiento
## Autores y Colaboradores ##
Gracias a [Miso](http://gomiso.com) por permitirme crear esto para nuestras aplicaciones y lanzar este proyecto.
* [Nathan Esquenazi](https://github.com/nesquena) - Creador del proyecto
* [Arthur Chiu](https://github.com/achiu) - Mantenedor principal, Gurú de pruebas Riot
* [Tim Lee](https://github.com/timothy1ee) - RABL fue un gran nombre elegido por el CTO de Miso.
* [David Sommers](https://github.com/databyte) - Resolución de plantillas, soporte de caché y mucho más
* [Rick Thomas](https://github.com/rickthomasjr) - Añadió opciones para extends y pruebas en Sinatra
* [Benjamin Yu](https://github.com/byu) - Añadió soporte para formato msgpack
* [Chris Kimpton](https://github.com/kimptoc) - Ayudando con la documentación y wiki
* [Marjun](https://github.com/mpagalan) - Añadió configuraciones de opciones XML
* [Anton Orel](https://github.com/skyeagle) - Añadió compatibilidad con Rails 3.1
* [Sasha Koss](https://github.com/kossnocorp) - Añadió soporte para multi_json
* [Matthew Schulkind](https://github.com/mschulkind) - Limpieza de configuración y pruebas
* [Luke van der Hoeven](https://github.com/plukevdh) - Soporte para objetos no ORM en plantillas
* [Andrey Voronkov](https://github.com/Antiarchitect) - Añadió soporte para formato BSON
* [Alli Witheford](https://github.com/alzeih) - Añadió soporte para formato Plist
* [Ryan Bigg](https://github.com/radar) - Mejoró el código de resolución de plantillas
* [Ivan Vanderbyl](https://github.com/ivanvanderbyl) - Añadió renderizador de propósito general
* [Cyril Mougel](https://github.com/shingara) - Añadió soporte conectable para cache_engine y ajustes en el renderizador
* [Teng Siong Ong](https://github.com/siong1987) - Mejoró la interfaz del renderizador
* [Brad Dunbar](https://github.com/braddunbar) - Pasa el objeto actual a los bloques
y muchos más colaboradores listados en el [CHANGELOG](https://github.com/nesquena/rabl/blob/master/CHANGELOG.md).
¿Quieres contribuir con soporte para otro formato? Consulta los parches para [soporte msgpack](https://github.com/nesquena/rabl/pull/69), [soporte plist](https://github.com/nesquena/rabl/pull/153) y [soporte BSON](https://github.com/nesquena/rabl/pull/163) como referencia.
Por favor, haz un fork y contribuye, ¡cualquier ayuda para mejorar este proyecto es apreciada!
Este proyecto es miembro del [Manifiesto OSS](http://ossmanifesto.org).
## Inspiraciones ##
Hay algunas librerías excelentes que ayudaron a inspirar RABL y se listan a continuación:
* [Tequila](https://github.com/inem/tequila)
* [JSON Builder](https://github.com/dewski/json_builder)
* [Argonaut](https://github.com/jbr/argonaut)
Gracias de nuevo por todos estos grandes proyectos.
## Copyright ##
Copyright © 2011-2012 Nathan Esquenazi. Consulta [MIT-LICENSE](https://github.com/nesquena/rabl/blob/master/MIT-LICENSE) para más detalles.