Le projet RAML vient d’annoncer la Release Candidate de la version 1.0. La spécification RAML 1.0 est disponible sur le site officiel.

Si vous de connaissez pas encore RAML, il n’est pas encore trop tard. C’est un langage de description d’une API RESTful. Si Swagger est une des solutions la plus pertinente et la plus utilisée pour documenter une API existante, ce n’est pas le cas pour une nouvelle API. RAML a été créé pour combler ce manque et se place au niveau de la conception et la documentation d’une API REST. Le langage se veut succinct et lisible par des humains.
C’est sûrement l’outil adapté si vous optez pour une démarche Contract-First. MuleSoft parle même de Design First quand ils lancent RAML.

Si vous ne vous êtes donc pas déjà lancé dans l’aventure RAML, n’hésitez pas à consulter cet article d’introduction à RAML qui explique comment concevoir une API d’Event Log avec RAML.

Pour ceux qui travaillaient déjà avec RAML 0.8, la liste des nouveautés de RAML 1.0 est la suivante :

  • Librairies : possibilité de définir un ensemble réutilisable de data types, ressources types, traits et security schemes au sein d’un namespace.
  • Overlays : définition de couches de documentation additionnelles via des fichiers RAML externes. Ces sur-couches peuvent être utiles pour internationaliser la documentation ou pour documenter des cas d’usages particuliers comme le monitoring de l’API.
  • Amélioration des schémas de sécurité : amélioration du support de OAuth 1 et 2, APIKey et sécurité personnalisée.
  • Annotations : pour permettre d’étendre le langage RAML par des applications tierces.
  • Data types : capacité à décrire des types de données via des types pré-définis, des valeurs par défaut, des règles de validation, différents types de collection, des types complexes réutilisant des types précédemment définis, etc…

Enfin, l’IDE APIWorkbench pour la conception, la construction, le test, la documentation et le partage d’API HTTP RESTful supporte à la fois la version 0.8 et 1.0 de RAML.

Avec cette version 1.0 proche de la version finale, RAML offre une solution mature pour concevoir, documenter et partager vos API REST. Il ne reste plus maintenant qu’à attendre la mise à jour de l’api:Console pour avoir le support de RAML 1.0.