cph/rabl-oldrabl 0.8.6 + fix for CVE-2014-4671
RABL (Ruby API Builder Language) est un système de templates Ruby pour Rails et Padrino permettant de générer du JSON, XML, MessagePack, PList et BSON. Lorsque j'utilise la méthode 'to_json' d'ActiveRecord, je me retrouve à vouloir une solution plus expressive et plus puissante pour générer des API. Cela est particulièrement vrai lorsque la représentation JSON est complexe ou ne correspond pas exactement au schéma défini dans la base de données.
En particulier, je veux facilement :
Quiconque a essayé la méthode 'to_json' utilisée dans ActiveRecord pour générer une réponse JSON a ressenti la douleur de cette approche restrictive. RABL est un système de templates général créé pour résoudre ces problèmes en abordant la génération de réponses API d'une manière entièrement nouvelle.
Au cœur de RABL, il s'agit de respecter les principes MVC en déléguant les représentations des données API à la couche vue de votre application. Pour une analyse des idées fausses courantes sur RABL, consultez notre guide pour comprendre RABL qui peut aider à dissiper toute confusion sur ce projet.
v0.8.0 (publié le 14 février 2013) supprime la dépendance multi_json et s'appuie sur Oj (ou JSON) comme analyseur JSON. Simplifie le code, supprime une dépendance, mais vous souhaiterez peut-être supprimer toutes les références à MultiJson.
v0.6.14 (publié le 28 juin 2012) nécessite l'utilisation de render_views avec RSpec pour tester les templates. Sinon, le contrôleur transmettra simplement la commande render comme il le fait avec les templates ERB.
Installer RABL en tant que gem :``` gem install rabl
ou ajoutez à votre Gemfile:```ruby
# Gemfile
gem 'rabl'
# Also add either `oj` or `yajl-ruby` as the JSON parser
gem 'oj'
et exécutez bundle install pour installer la dépendance.
Si vous utilisez Rails 2.3.8 (et versions ultérieures), Rails 3.X ou Padrino, RABL fonctionne sans configuration.
Important : Avec Padrino, assurez-vous que la gem rabl est listée après la gem padrino dans votre Gemfile, sinon Rabl ne s'enregistrera pas correctement comme moteur de template.
Avec Sinatra, ou tout autre framework basé sur tilt, inscrivez-le simplement :```ruby Rabl.register!
et RABL sera initialisé et prêt à être utilisé. Pour une utilisation avec Sinatra, consultez le guide [Utilisation de Sinatra](https://github.com/nesquena/rabl/wiki/Setup-for-Sinatra).
## Aperçu ##
Vous pouvez utiliser RABL pour générer des API basées sur JSON et XML à partir de n'importe quel objet Ruby. Avec RABL, les données sont généralement dérivées principalement des modèles (indépendants de l'ORM) et la représentation de la sortie de l'API est décrite dans un template de vue utilisant un simple DSL Ruby. Cela vous permet de garder vos données séparées du JSON ou XML que vous souhaitez produire.
Une fois que vous avez installé RABL (expliqué ci-dessus), vous pouvez construire un template de vue RABL puis rendre le template depuis vos applications Sinatra, Padrino ou Rails depuis le contrôleur (ou la route) très facilement. En utilisant [Padrino](http://padrinorb.com) comme exemple, en supposant que vous avez un modèle `Post` rempli d'articles de blog, vous pouvez rendre une représentation API (à la fois JSON et XML) en créant une route :```ruby
# app/app.rb
get "/posts", :provides => [:json, :xml] do
@user = current_user
@posts = Post.order("id DESC")
render "posts/index"
end
Ensuite nous pouvons créer le modèle RABL suivant pour exprimer la sortie de l'API de @posts :```ruby
collection @posts attributes :id, :title, :subject child(:user) { attributes :full_name } node(:read) { |post| post.read_by?(@user) }
Ce qui produirait le JSON ou XML suivant lors de la visite de `http://localhost:3000/posts.json````js
[{ "post" :
{
"id" : 5, title: "...", subject: "...",
"user" : { full_name : "..." },
"read" : true
}
}]
Voici un aperçu de base, mais il y a bien plus à voir comme les partials, l'héritage, les nœuds personnalisés, etc. Lisez les détails complets de RABL ci-dessous.
RABL est conçu pour nécessiter peu ou pas de configuration pour fonctionner. C'est le cas dans la plupart des scénarios, mais selon vos besoins, vous pouvez définir les configurations globales suivantes dans votre application (ce bloc est entièrement facultatif) :```ruby
require 'rabl' Rabl.configure do |config|
end
Chaque option spécifie un comportement lié à la sortie de RABL. Si `include_json_root` est désactivé, cela supprime le
nœud racine de chaque objet racine dans la sortie, et `enable_json_callbacks` active la prise en charge du style de sortie « jsonp »
si la requête entrante possède un paramètre « callback ».
Si `include_child_root` est défini sur false, les objets enfants dans la réponse n'incluront pas
de nœud racine par défaut. Cela permet d'affiner davantage la structure de réponse souhaitée.
Si `cache_engine` est défini, vous devez l'affecter à une classe avec une méthode `fetch`. Voir le [moteur par défaut](https://github.com/nesquena/rabl/blob/master/lib/rabl/cache_engine.rb) pour un exemple.
Si `perform_caching` est défini sur `true`, la mise en cache sera effectuée. Vous
pouvez ignorer cette option si vous utilisez Rails, c'est la même chose que
`config.action_controller.perform_caching` de Rails.
Si `cache_sources` est défini sur `true`, les recherches de templates seront mises en cache pour des performances améliorées.
Le cache peut être réinitialisé manuellement en exécutant `Rabl.reset_source_cache!` dans votre application.
Si `cache_all_output` est défini sur `true`, chaque template, y compris chaque template individuel utilisé dans le cadre d'une collection, sera mis en cache séparément.
De plus, tout ce qui se trouve à l'intérieur de child, glue et partial sera également mis en cache séparément.
Pour mettre en cache un seul template, voir la section intitulée « Caching » ci-dessous.
Si `escape_all_output` est défini sur `true` et qu'ActiveSupport est disponible, la sortie des attributs sera échappée en utilisant [ERB::Util.html_escape](http://corelib.rubyonrails.org/classes/ERB/Util.html).
Les nœuds personnalisés ne seront pas échappés, utilisez `ERB::Util.h(value)`.
Si `view_paths` est défini sur un chemin, ce chemin de vue sera vérifié pour chaque template rabl dans votre application.
Ajoutez à ce chemin surtout lorsque vous incluez Rabl dans un moteur et utilisez des chemins de vue dans une autre application Rails.
Si `raise_on_missing_attribute` est défini sur `true`, une RuntimeError sera levée chaque fois que Rabl
tente de rendre un attribut qui n'existe pas. Sinon, l'attribut sera simplement omis.
Définir ceci sur true pendant le développement peut aider à augmenter la robustesse de votre code, mais utiliser `true` dans
le code de production n'est pas recommandé.
Si `replace_nil_values_with_empty_strings` est défini sur `true`, toutes les valeurs qui sont `nil` et qui seraient normalement affichées comme `null` dans la réponse sont converties en chaînes vides.
Si vous souhaitez utiliser [oj](https://github.com/ohler55/oj) comme
moteur principale d'encodage JSON, ajoutez-le simplement à votre Gemfile :```ruby
# Gemfile
gem 'oj'
et RABL utilisera automatiquement ce moteur pour encoder vos réponses JSON. Définissez votre propre json_engine personnalisé qui définit une méthode dump ou encode pour convertir en JSON à partir de données Ruby :```ruby
config.json_engine = ActiveSupport::JSON
### Configuration des formats ###
RABL prend en charge la configuration pour MessagePack, BSON et Plist. Consultez la page
[Format Configuration](https://github.com/nesquena/rabl/wiki/Configuring-Formats) pour plus de détails.
## Utilisation ##
### Affectation d'objet ###
Pour déclarer l'objet de données à utiliser dans le template :```ruby
# app/views/users/show.json.rabl
object @user
ou spécifiez un alias pour l'objet :```ruby object @user => :person
ou passer une collection d'objets :```ruby
collection @users
# => [ { "user" : { ... } } ]
ou spécifiez une étiquette de nœud racine pour la collection :```ruby collection @users => :people
ou même spécifier à la fois les étiquettes enfant et racine pour une collection :```ruby
collection @users, :root => "people", :object_root => "user"
# => { "people" : [ { "user" : { ... } } ] }
et cela sera utilisé comme données par défaut pour le rendu, ou désactiver explicitement la racine de l'objet :```ruby collection @users, :root => "people", :object_root => false
Il peut également y avoir des cas étranges où le niveau racine de la réponse ne correspond directement à aucun objet :```ruby
object false
node(:some_count) { |m| @user.posts.count }
child(@user) { attribute :name }
Dans ces cas, object peut être assigné à 'false' et nodes peuvent être construits librement.
Utilisation de base du templater pour définir quelques attributs simples pour la réponse :```ruby
attributes :id, :foo, :bar
ou utiliser avec des attributs aliasés :```ruby
# Take the value of model attribute `foo` and name the node `bar`
attribute :foo => :bar
# => { bar : 5 }
ou même plusieurs attributs aliasés :```ruby attributes :bar => :baz, :dog => :animal
ou afficher les attributs seulement si une condition est vraie :```ruby
# m is the object being rendered, also supports :unless
attributes :foo, :bar, :if => lambda { |m| m.condition? }
Les attributs nommés et aliasés ne peuvent pas être combinés sur la même ligne. Cela ne fonctionne actuellement pas :```ruby attributes :foo, :bar => :baz # throws exception
### Nœuds Enfants ###
Souvent, une réponse nécessite d'inclure des informations imbriquées provenant de données associées au modèle parent :```ruby
child :address do
attributes :street, :city, :zip, :state
end
Vous pouvez également désactiver la racine d'objet pour le nœud enfant :```ruby child :posts, :object_root => false do attributes :id, :title end
Vous pouvez également ajouter des nœuds enfants à partir d'une source de données arbitraire :```ruby
child @posts => :foobar do
attributes :id, :title
end
ou utilisez les associations de modèles avec un alias :```ruby
child :posts => :foobar do attributes :id, :title end
Vous pouvez également passer l'objet courant :```ruby
object @user
child :posts do |user|
attribute :title unless user.suspended?
end
Vous pouvez également ajouter des attributs enfants au nœud racine :```ruby
glue @post do attributes :id => :post_id, :name => :post_name end
Utilisez glue pour ajouter des attributs supplémentaires à l'objet parent.
Vous pouvez également passer l'objet courant :```ruby
object @user
glue(@post) {|user| attribute :title if user.active? }
Cela générera une réponse json basée sur le résultat du bloc node:```ruby
node :full_name do |u| u.first_name + " " + u.last_name end
ou un nœud personnalisé qui n'existe que si une condition est vraie :```ruby
# m is the object being rendered, also supports :unless
node(:foo, :if => lambda { |m| m.has_foo? }) do |m|
m.foo
end
ou ne pas passer de nom et faire fusionner le bloc node dans la réponse :```ruby node do |u| { :full_name => u.first_name + " " + u.last_name }
end
Vous pouvez utiliser des nœuds personnalisés comme ceux-ci pour créer des représentations flexibles d'une valeur en utilisant toutes les données du modèle.
### Partials ###
Souvent, vous devez accéder à d'autres objets de données afin de construire des nœuds personnalisés dans des associations plus complexes. Vous pouvez accéder à la représentation rabl d'un autre objet de données en rendant un partiel RABL :```ruby
node :location do
{ :city => @city, :address => partial("users/address", :object => @address) }
end
ou même accéder à un objet associé au modèle parent :```ruby node :location do |m| { :city => m.city, :address => partial("users/address", :object => m.address) } end
Vous pouvez utiliser cette méthode pour construire des nœuds arbitrairement complexes pour vos API. Notez que vous devez avoir des modèles RABL définis
pour chacun des objets dont vous souhaitez construire des représentations de cette manière.
### Héritage ###
Un autre problème courant avec de nombreux constructeurs de modèles est la redondance inutile de code. Typiquement, de nombreuses représentations d'un objet à travers plusieurs points d'accès partagent des attributs ou nœuds communs. Les nœuds pour un objet 'post' sont probablement les mêmes ou similaires dans la plupart des références à travers les différents points d'accès.
RABL a la capacité d'étendre d'autres modèles rabl 'de base' et des attributs supplémentaires :```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
Vous pouvez également étendre d'autres templates rabl lors de la construction de nœuds enfants pour réduire la duplication :```ruby
child @address do extends "address/item" end
L'utilisation de partials et d'héritage peut considérablement réduire la duplication de code dans vos templates.
Vous pouvez voir plus d'exemples sur la [page wiki Réutilisation des templates](https://github.com/nesquena/rabl/wiki/Reusing-templates).
### Passage de variables locales dans les partials ###
Vous pouvez passer un ensemble arbitraire de variables locales lors du rendu de partials ou de l'extension de templates.
Par exemple, si nous voulons afficher sur `posts/:id.json` toutes les informations concernant un post particulier et ses commentaires associés,
mais dans d'autres cas nous voulons masquer ces commentaires. Nous pouvons utiliser des variables locales pour ce faire :```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 })}
puis accéder aux variables locales dans le sous-modèle :```ruby
object @post
attributes :id, :title, :body, :created_at node(:comments) { |post| post.comments } unless locals[:hide_comments]
Cela peut être utile comme outil avancé lors de l'extension ou du rendu de partials.
### Template Scope ###
Dans RABL, vous avez accès à tout ce dont vous avez besoin pour construire une réponse API. Chaque template RABL a un accès complet aux variables d'instance des contrôleurs ainsi qu'à tous les helpers de vue et aux URLs de routage.```ruby
# app/some/template.rabl
object @post
# Access instance variables
child(@user => :user) { ... }
# or Rails helpers
node(:formatted_body) { |post| simple_format(post.body) }
Il ne devrait y avoir aucun problème à récupérer les données appropriées pour construire une réponse.
Dans les API, vous pouvez souvent avoir besoin de construire des nœuds de 2e ou 3e niveau. Supposons que nous ayons un modèle 'quiz' qui a de nombreuses 'questions' et que chaque question a de nombreuses 'réponses'. Nous pouvons afficher cette hiérarchie en RABL assez facilement :```ruby
object @quiz attribute :title child :questions do attribute :caption child :answers do # Use inheritance to reduce duplication extends "answers/item" end end
Cela affichera l'objet quiz avec des questions et réponses imbriquées comme on peut s'y attendre avec un nœud quiz, et des questions et réponses intégrées.
Notez que RABL peut être imbriqué arbitrairement profondément dans les nœuds enfants pour permettre ces représentations.
### Mise en cache ###
RABL prend en charge la mise en cache intégrée pour les modèles tirant parti des stratégies de mise en cache fragmentaire. Notez que la mise en cache n'est actuellement **uniquement disponible** pour Rails, mais le support pour d'autres frameworks est prévu dans une future version. L'utilisation la plus simple de la mise en cache est :```ruby
# app/views/users/show.json.rabl
object @quiz
cache @quiz # key = rabl/quiz/[cache_key]
attribute :title
La mise en cache peut considérablement accélérer le rendu des modèles RABL en production et est fortement recommandée lorsque c'est possible. Pour un aperçu plus détaillé de la mise en cache, consultez le guide Caching sur le wiki.
Il existe des situations où une application nécessite que des modèles RABL soient rendus en dehors d'un contexte de vue traditionnel. Par exemple, pour rendre RABL dans une tâche Rake ou pour créer des charges utiles de file d'attente de messages. Dans ce cas, Rabl.render peut être utilisé comme indiqué ci-dessous :```ruby
Rabl.render(object, template, :view_path => 'app/views', :format => :json) #=> "{...json...}"
Vous pouvez utiliser des méthodes de commodité sur `Rabl::Renderer` pour également rendre les objets :```ruby
Rabl::Renderer.json(@post, 'posts/show')
Rabl::Renderer.xml(@post, 'posts/show')
Ces méthodes permettent d'utiliser RABL pour des conversions arbitraires d'un objet dans un format souhaité.```ruby Rabl::Renderer.new('posts/show', @post, :view_path => 'app/views', :format => 'hash').render
Vous pouvez également passer d'autres variables d'instance à utiliser dans votre modèle comme :```ruby
Rabl::Renderer.new('posts/show', @post, :locals => { :custom_title => "Hello world!" })
Ensuite, dans votre modèle, vous pouvez utiliser @custom_title comme :```
attribute :content
node(:title) { @custom_title }
### En-têtes de type de contenu ###
Actuellement dans RABL, le type de contenu de votre réponse n'est pas défini automatiquement. Cela est dû au fait que RABL est conçu
pour fonctionner avec n'importe quel framework basé sur Rack et aussi agnostique que possible en termes de format.
Consultez [ce problème](https://github.com/nesquena/rabl/issues/185#issuecomment-4501232) pour plus de
détails, et si vous avez des idées ou des correctifs, n'hésitez pas à me le faire savoir.
En attendant, assurez-vous de définir les types de contenu appropriés si nécessaire. C'est généralement assez simple à la fois dans
Rails et Padrino. Je recommande un before_filter sur ce contrôleur ou une spécification directe dans une action.
## Ressources ##
De nombreuses ressources sont disponibles concernant RABL, notamment le [Wiki RABL](https://github.com/nesquena/rabl/wiki),
ainsi que de nombreux tutoriels et guides détaillés ci-dessous.
Vous pouvez également consulter le [Site RABL](http://nesquena.github.com/rabl).
### Utilisation avancée ###
Liens vers des ressources pour une utilisation avancée :
* [Gestion de la complexité](https://github.com/nesquena/rabl/wiki/Managing-complexity-with-presenters)
* [Optimisations de production](https://github.com/nesquena/rabl/wiki/Rabl-In-Production)
* [Intégration Grape](https://github.com/nesquena/rabl/wiki/Using-Rabl-with-Grape)
* [Rendu JSON pour une structure arborescente avec RABL](https://github.com/nesquena/rabl/issues/70)
* [Layouts (erb, haml et rabl) dans RABL](https://github.com/nesquena/rabl/wiki/Using-Layouts)
* [Intégration Backbone ou Ember.js](https://github.com/nesquena/rabl/wiki/Backbone-Integration)
* [RABL avec Rails Engines](https://github.com/nesquena/rabl/wiki/Setup-rabl-with-rails-engines)
N'hésitez pas à ajouter vos propres utilisations et à me le faire savoir pour que nous puissions les ajouter ici ! Assurez-vous également de consulter
le [Wiki RABL](https://github.com/nesquena/rabl/wiki) pour d'autres utilisations.
### Tutoriels ###
Les tutoriels peuvent toujours être utiles pour débuter :
* [Railscasts #322](http://railscasts.com/episodes/322-rabl) - Ryan Bates explique RABL
* [BackboneRails](http://www.backbonerails.com/) - D'excellents screencasts par Brian Mann
* [Création d'une API avec RABL et 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
Faites-moi savoir s'il y a d'autres ressources utiles non répertoriées ici.
### Bibliothèques associées ###
Il existe d'autres bibliothèques qui peuvent compléter ou étendre les fonctionnalités de RABL :
* [versioncake](https://github.com/bwillis/versioncake) - Excellente bibliothèque pour versionner facilement vos API RABL
* [gon](https://github.com/gazay/gon) - Expose vos variables Rails en JS avec le support intégré de RABL.
* [rabl-rails](https://github.com/ccocchi/rabl-rails) - Réimplémentation pour RABL et Rails
[axée sur la vitesse](https://github.com/ccocchi/rabl-benchmark/blob/master/BENCHMARK).
Faites-moi savoir s'il y a d'autres bibliothèques associées non répertoriées ici.
### Dépannage ###
* [Appels redondants pour une collection](https://github.com/nesquena/rabl/issues/142#issuecomment-2969107)
* [Test des vues RABL](https://github.com/nesquena/rabl/issues/130#issuecomment-4179285)
### Exemples ###
Consultez le répertoire [exemples](https://github.com/nesquena/rabl/tree/master/examples).
## Problèmes ##
Consultez l'onglet [Problèmes](https://github.com/nesquena/rabl/issues) pour une liste complète :
* Benchmark rigoureux et optimisations des performances
## Auteurs et contributeurs ##
Merci à [Miso](http://gomiso.com) de m'avoir permis de créer cela pour nos applications et de publier ce projet !
* [Nathan Esquenazi](https://github.com/nesquena) - Créateur du projet
* [Arthur Chiu](https://github.com/achiu) - Mainteneur principal, gourou des tests Riot
* [Tim Lee](https://github.com/timothy1ee) - RABL était un excellent nom choisi par le CTO de Miso.
* [David Sommers](https://github.com/databyte) - Résolution de template, support de cache, et bien plus
* [Rick Thomas](https://github.com/rickthomasjr) - Ajout d'options pour extends et tests Sinatra
* [Benjamin Yu](https://github.com/byu) - Ajout du support du format msgpack
* [Chris Kimpton](https://github.com/kimptoc) - Aide pour la documentation et le wiki
* [Marjun](https://github.com/mpagalan) - Ajout des configurations d'options xml
* [Anton Orel](https://github.com/skyeagle) - Ajout de la compatibilité Rails 3.1
* [Sasha Koss](https://github.com/kossnocorp) - Ajout du support multi_json
* [Matthew Schulkind](https://github.com/mschulkind) - Nettoyage de la configuration et des tests
* [Luke van der Hoeven](https://github.com/plukevdh) - Support des objets non-ORM dans les templates
* [Andrey Voronkov](https://github.com/Antiarchitect) - Ajout du support du format BSON
* [Alli Witheford](https://github.com/alzeih) - Ajout du support du format Plist
* [Ryan Bigg](https://github.com/radar) - Amélioration du code de résolution de template
* [Ivan Vanderbyl](https://github.com/ivanvanderbyl) - Ajout du moteur de rendu général
* [Cyril Mougel](https://github.com/shingara) - Ajout du support enfichable de cache_engine et ajustements du rendu
* [Teng Siong Ong](https://github.com/siong1987) - Amélioration de l'interface de rendu
* [Brad Dunbar](https://github.com/braddunbar) - Passage de l'objet courant dans les blocs
et bien d'autres contributeurs listés dans le [CHANGELOG](https://github.com/nesquena/rabl/blob/master/CHANGELOG.md).
Vous souhaitez contribuer au support d'un autre format ?
Consultez les correctifs pour le [support msgpack](https://github.com/nesquena/rabl/pull/69), le [support plist](https://github.com/nesquena/rabl/pull/153) et
le [support BSON](https://github.com/nesquena/rabl/pull/163) pour référence.
N'hésitez pas à forker et à contribuer, toute aide pour améliorer ce projet est appréciée !
Ce projet est membre du [Manifeste OSS](http://ossmanifesto.org).
## Inspirations ##
Quelques excellentes bibliothèques ont contribué à inspirer RABL et sont listées ci-dessous :
* [Tequila](https://github.com/inem/tequila)
* [JSON Builder](https://github.com/dewski/json_builder)
* [Argonaut](https://github.com/jbr/argonaut)
Merci encore pour tous ces grands projets.
## Copyright ##
Copyright © 2011-2012 Nathan Esquenazi. Voir [MIT-LICENSE](https://github.com/nesquena/rabl/blob/master/MIT-LICENSE) pour les détails.