Avoir une API REST c’est cool, avoir une API REST documentée c’est encore mieux!

Quelques exemples de documentation d’API REST

• Expedia : plain text, pas super pratique
• Twitter : c’est déjà mieux
• Marvel : waouh!

A mon humble avis la doc la plus lisible et mieux organisée est celle de l’API de Marvel.

Elle a été générée grâce à Swagger. Swagger permet pour une application Java et plus particulièrement une application JAX-RS, de générer cette documentation et ceci grâce à des annotations ( exemple ). Il existe aussi un module Swagger pour Play2 qui utilise lui aussi des annotations.

C’est bien sympa tout ca, ca génère tout tout seul mais c’est tout de même super intrusif et ca “pollue” quelque peu notre code. Il y a presque plus d’annotations Swagger que de code…

RAML

RAML ou RESTful API Modeling Language, est une initiative de Mulesoft mais pas que. L’idée de RAML ce n’est pas de générer de la doc à partir de code existant mais de définir un language de description d’APIs REST. Il se base sur YAML et a donc sa propre specification.

RAML.org fournit différents outils open source :

API Designer

Un editeur développé en AngularJS permettant de créer des fichiers RAML. L’éditeur a la coloration syntaxique, l’auto-complétion ainsi que la vérification de la syntaxe RAML. En attenant un plugin équivalent pour votre IDE préféré, cela reste le meilleur outil pour éditer un fichier RAML. Il utilise lui même l’API Console pour faire la prévisualisation des fichiers édités. Pour l’utiliser localement, il suffit de cloner le repo github puis de lancer l’application grâce à grunt. Personnellement je préfère utiliser l’éditeur en ligne car en local je n’ai pas trouvé comment persister les fichiers :)

API Console

Une directive AngularJS permettant de faire un rendu web d’un fichier RAML donné.

JAX-RS Codegen

Un générateur d’application JAX-RS a partir d’un fichier RAML.

Exemple

Voilà la description de la Foo REST API v1 accessible à l’url http://api.mydomain.com/v1 .

Cette API décrit succintement des actions CRUD sur des places. On peut ainsi récupérer une liste de places potentiellement triée et paginée si on le souhaite (query parameters). L’API permet aussi de récupérer une place au format JSON en faisant un GET sur places/{id} (où id est un nombre), de modifier la place via un POST, ou de la supprimer avec un DELETE.

Dans l’API Designer avec la preview :

Un exemple concret

Afin de se rendre bien compte de la syntaxe et des possibilités offertes par RAML, voilà un exemple concret de doc générée pour l’API de Github et le fichier RAML source.

RAML permet de définir des traits, des type de resources (dans l’exemple de l’API Github il y a par exemple le resourceType item pour les URI vers une ressource unique et collection pour les listes) ce qui permet d’éviter de se répéter mais aussi de bien catégoriser et organiser ses ressources.

Pour les réponses, on peut spécifier directement dans le fichier RAML la structure d’un objet json au format json-schema dans le cadre d’une réponse de type application/json mais on peut aussi inclure (grace à la syntaxe !include:myfile ) un fichier json ou une xsd (pour une réponse de type application/xml). La même chose est possible pour les exemples de réponses. Ce qu’il faut savoir avec les exemples, c’est qu’ils vont être les valeurs par défaut dans l’onglet Try it.

On pourrait alors imaginer, dans le cas où l’ont veut documenter une application existante (je rappelle que l’idée de base de RAML c’est de décrire d’abord l’API puis de générer le code à partir de cette spec), pour une application Play2 Scala, un plugin SBT permettant de générer des fichiers json décrivant au format json-schema tous les Readers/Writers définis dans l’application. Ca serait toujours plus pratique que devoir les écrire “à la main”.

Conclusion

REST API Designer est un métier d’avenir. Bien construire une API REST n’est pas forcément évident (cf ce thread). Des outils comme ceux que proposent RAML (en particulier l’API Designer et l’API Console) me semblent plus qu’adaptés pour tous ceux qui doivent créer une API REST ou documenter une existante.

et dire qu’il y a deux ans je ne savais pas ce qu’était un JUG…

Avant de rentrer dans le vif du sujet et de faire un long compte-rendu de mes toutes premières conférences, je suis obligé de parler un peu de mon parcours.
J’ai fait mes premiers en Java en 1998 à l’IUT info de Montpellier. J’ai mis 10 ans avant d’en refaire.
Entre temps, j’ai commencé ma vie professionnelle en 2001 à Paris avec du client lourd windows (C++, MFC), des bases Oracle, puis du PL/SQL. Après 4 ans, retour en province à Toulouse avec une étiquette “développeur PL/SQL” (dur à s’en défaire quand on est dans une grosse SSII). Après donc 3 ans à ronger mon frein, à découvrir ExtJS, à s’initier au web avec un peu de PHP, je retrouve enfin Java et plus partculièrement GWT. Il y a maintenant presque 2 ans, je débarque en région PACA, à Aubagne (connue mondialement pour ses santons, Marcel Pagnol et sa légion).
Autant dire que je ne croulais pas trop sous le travail et me taper 100 bornes par jour (les SSII sont concentrées du coté d’Aix) pour rien faire, j’occupe mon temps à faire de la veille. Je découvre alors les castcodeurs, ce qu’est un JUG et qu’en fait une énorme communauté Java existe. Je plonge dans le livre d’Antonio et tombe amoureux de Java EE 6, délaisse GXT pour JSF2 et en particulier Primefaces.
On essaye de m’occuper en me demandant pour une avant-vente de me renseigner sur l’intégration continue. Je tombe des nues. Mais pourquoi on en a jamais fait sur mes anciens projets?! On aurait peut-etre pas consommé le double que prévu!
Bref, je me rends compte que dans ces fameuses grosses boites, personne ne sait ce qu’est qu’un JUG, ne fait vraiment de veille… A cela on m’annonce que l’agence veut se focaliser sur Sharepoint et Cobol… je décide de changer d’air.
Depuis maintenant presqu’un an je suis dans une petite structure (< 50 personnes). A la base “Référent SQL”, je suis plutôt “Integration manager”. J’ai fait une migration de CVS vers Git, mis en place Jenkins pour faire de l’intégration continue (plus de 300 jobs créés), …
Et je vais régulièrement au MarsJug, je ne loupe quasiment aucune session.

Donc quand j’ai vu les annonces conjuguées de DevoxxFr et de la Jenkins User Conference à Paris, il m’a semblé évident qu’il fallait que j’y aille. C’était dans la continuité de mon évolution professionnelle commencée il y a maintenant 2 ans.
Je pense que si j’étais resté dans la grosse boite je n’aurais jamais pu y aller.

Attaquons donc le vif du sujet et mon compte-rendu des deux premières conférences de ma vie.

Jenkins User Conference

Premier jour soft au Mariott.

Pendant que l’équipe de DevoxxFr s’attèle aux derniers préparatifs au rez-de-chaussée, la JUC se tient au sous-sol. Je n’ai pas les chiffres exacts mais selon Nicolas de Loof il devait y avoir une grosse centaine de participants. La conf est résolument plus internationale que DevoxxFr puisque, si je ne me trompe, c’est la première JUC européenne. Il y a donc des partipants venus d’Angletterre, Allemagne, Hollande, …
Après une rapide introduction de Sacha Labourey, KK, le créateur de Jenkins, fait une courte keynote retraçant l’histoire de son bébé.
A partir de là, les sessions auront lieu dans deux salles en parallèle.
Voilà le résumé de mon programme :

Better Build Pipeline : introducing Build-Flow plugin

par Nicolas de Loof et Matthieu Ancelin
J’ai découvert Nicolas à ma première session au MarsJug. A l’époque il baignait dans GWT et pas encore dans Jenkins.
J’utilise le Build Pipeline plugin sur mes 3 Jenkins, il me permet de me servir de Jenkins plus comme un ordonnanceur à la Dollar Universe plus qu’un simple serveur de build. J’ai ainsi un pipeline de mise en production qui permet de suivre la déploiement sur une vingtaine de serveurs.
L’idée originale de Nicolas, il me semble, était de fusionner le Join plugin et le Build Pipeline plugin. Au final il s’est carrément emballé et est allé jusqu’à créer un DSL pour représenter des workflows. Le plugin est prometteur. Un gros chantier est la représentation graphique (l’interêt principal du Build Pipeline plugin) qui reste à faire. Et vu le nombre de questions à la fin de la présentation, ce plugin a un bel avenir devant lui!

Native Package Build Factory Powered by Jenkins

par Henri Gomez
J’ai aussi découvert Henri au MarsJug. Il m’a donné de précieux conseils pour la mise en place de jenkins.
Henri a été un peu pris de court, il avait préparé sont talk en français et a du le faire en anglais au dernier moment.
Henri présente les avantages du packaging natif (c’est son coté Ops). Avec le Matrix Job plugin, il montre comment créer des RPMS par plateforme/architecture. Dans son talk du lendemain avec les 4 autres mercenaires, tout ceci sera mis en application.

Advanced Continuous Deployment with Jenkins

par Benoit Moussaud
Benoit de Xebia Labs présente Deploy-IT, un outil maison qui permet de déployer par drag’n’drop des livrables sur des serveurs. J’avoue que j’ai été un peu déçu. Pas par l’outil, mais je m”attendais plus à un talk sur des best practices de continuous deployment qu’à une présentation technico-commerciale d’un produit.

Tycho, Jenkins & Sonar : the Eclipse Build Dream Team

par Xavier Seignard et Mickael Istria
Vu que c’était sur l’utilisation de Jenkins lors du développement de plugin Eclipse, ce n’était pas trop pour moi.

Clearcase UCM plugin

par Jens Brejner
Alors je n’ai jamais utilisé Clearcase, mais ce talk a eu un franc succès en abordant un sujet interessant : la notion de pre-tested commit.

Jenkins at Nuxeo

par Julien Carsique
Une présentation 101 pour ceux qui n’utilisent pas encore Jenkins.

Integrating PHP Projects with Jenkins

par Sebastian Bergmann
Autant le dire franchement, le pauvre Sebastian n’a pas vraiment eu de public. Dans la grande salle il n’y avait à peine 10 personnes qui étaient intéressées par l’intégration continue de projets PHP.
Personnellement j’ai une partie PHP à gérer et j’ai essayé, en vain, de faire un job Jenkins qui déclencherait une analyse statique de code et un reporting dans Sonar. Faut dire que j’ai opté pour une solution proposée dans le wiki du plugin PHP de Sonar :
créer un projet maven et y mettre les sources PHP.
Le talk de Sebastian reprend ce qui est dit sur son site jenkins-php et présente les différents outils propres à PHP (PHPUnit, PHPmd, …).

Conclusion

Je m’attendais à des talks un peu plus poussés, en même temps mon choix n’était peut-etre pas le bon. J’aurais peut-etre du aller voir Grégory Boissinot et son talk How to develop a Jenkins plugin, ou les quickies sur Jenkins chez Apache par Olivier Lamy, la présentation du Template Plugin, …

ou comment créer un éditeur de formation de football

Depuis début 2011 je me suis mis à JSF2, si décrié par certain, et j’ai découvert Primefaces. J’ai rapidement accroché car tout simplement je l’ai trouvé plus joli que les cadors du marchés (RichFaces, IceFaces, ..) et puis aussi parce que les exemples du showcase de Primefaces m’ont beaucoup interessé puisqu’ils sont souvent basés sur des données liées au joueurs du FC Barcelone. Et vu que mon projet est lié au foot, j’ai de suite eu des idées sur comment mettre en oeuvre

J’utilise la version de développement de Primefaces (3.0-RC1-SNAPSHOT à ce jour) et la version finale (3.0) est prévue pour très bientôt. Mon environnement de développement est très standard : Netbeans 7, Glassfish 3.1.1, le tout sous linux. Coté base de données, après avoir tetsé du Derby j’utilise aussi MySql.

Rentrons dans le vif du sujet : le but est de créer un composant (bien que ce ne va pas être un composant JSF à proprement parler) qui permettra de définir la position de joueurs afin de définir un schéma de jeu (les fameux 4-4-2, 4-3-3 que connaissent les footeux).

Pour cela j’ai défini 2 entités que l’on va persister (je ne vais pas m’attarder sur la partie JPA2-EJB3 dans cette article) : La première; Formation, représente une formation (ou schéma tactique) :

La deuxième entité, FormationItem, représentera les différents postes d’une formation :

Passons aux choses sérieuses coté JSF. L’idée va être de positionner les différentes FormationItem selon une grille, c’est à ça que sert la propriété FamFormation.coord, à représenter la case de la grille sur laquelle le FormationItem.numItem es positionné.

On ne va pas persister cette grille mais par contre on va avoir besoin d’un petit JSF Bean pour nous aider à faire cette représentation :

Ce bean va représenter chaque case de la grille que l’on va créer. Chaque case à un index et potentiellement un FormationItem.

Il ne reste plus qu’à créer un Controller et une page JSF.

Dans le controller on va avoir besoin de :

Coté JSF, on va utiliser le composant DataGrid de PrimeFaces. Il permet d’afficher les données d’une ArrayList sur différentes colonnes, de paginer ou pas cette ArrayList, … bref, il va nous permettre d’afficher notre grille. Personnellement j’ai choisi une grille de 5*6 soit 30 cases. Mais on pourrait très bien affiner le positionnement des FormationItem en augmentant le nombre de cases. A l’affichage de notre page, il faut donc avoir construit une ArrayList de 30 CanvasFormationItem.

Basculons coté Web : On va avoir besoin d’une petite fonction javascript (toute petite et c’est la seule).

D’abord un petit formulaire pour la Formation

et maintenant la fameuse DataGrid :

On a rajouté un listener sur l’action onDrop, il faut donc le coder dans le Controller. On va gérer les modifications de coords sur les FormationItem dans ce listener. Puis en rafraichissant la DataGrid, ca sera automatiquement pris en compte.

Et voilà!

mon blog sous github

Voilà, j’ai suivi cet excellent tutorial et j’ai donc créé mon blog sous github comme tout bon geek qui se respecte :D