Dernière mise à jour du document (v1.0.0) : 17 juillet 2017.
La coopérative dtc innovation a été contactée par la Direction du Numérique de Radio France suite à une mise en relation de Jolicode.
La Direction du Numérique souhaitait obtenir davantage de visibilité sur ses applications JavaScript en sollicitant un audit de ses applications Node — principalement du côté de son équipe API. Cet audit s’inscrit dans la lignée d’un audit de leurs applications PHP.
L’objectif de cet audit est multiple :
faire un point sur leur parc applicatif JavaScript et Node ;
obtenir un regard sur les habitudes de l’équipe ;
augmenter la visibilité sur ce qui est produit par les équipes ;
dans un monde idéal, atteindre un niveau où tout code serait open sourçable (aka. inner source).
L’audit débutera d’abord par l'établissement d’un périmètre fonctionnel (scope) pour ensuite définir des missions d’actions ciblées, généralement courtes et clairement délimitées.
Ce document résume ce que nous avons observé les 15 et 16 juin puis le 5 juillet 2017 dans les locaux de la Direction du Numérique chez Radio France.
Ce document contient également des pistes d’actions ainsi que des recommandations pouvant appuyer et soutenir la stratégie moyen et long terme de Radio France dans son innovation numérique.
Arrivée et accueil
Matinée : présentation par l’équipe API ("cruiser") de l’architecture du back-end web et de la communication entre les micro-services
Présence à la "Foire au Cruiser" l’après-midi
Discussions avec les différents membres de l’équipe API
Restitution des différents axes d’amélioration que nous avons entendu et discussion avec l’équipe API pour la priorisation de ces points
Discussions avec d’autres équipes sur le même plateau
UX
SEO
France Culture
France Bleu
Discussions avec les différents membres de l’équipe API
Discussions avec d’autres équipes sur le même plateau
Back-Office
Terry dans l’équipe France Bleu — il a aidé à la mise en place du SDK PHP et récupéré le lead depuis 1 semaine
Mobile natif
Direction du numérique
Restitution de l’audit
Nous sommes ressortis avec un sentiment très positif suite à ce que nous avons pu observer à la Direction du Numérique.
De nombreux signaux ont l’air d’être au vert :
Concernant la technique, les choix sont simples, cohérents en soi et entre eux, pas de gros risques sur des technologies, un parti pris sur l’indépendance logicielle (pas de services en SaaS) ;
Le premier matin, la clarté de l’explication de l’architecture était en elle-même un signe de la qualité de l’architecture ;
Ne pas hésiter à payer pour du support spécifique quand un problème apparait et qu’un manque de compétence est identifié est une très bonne décision aussi ;
Nous ne connaissons pas les détails financiers, mais les ambitions ont l’air en adéquation avec les moyens à disposition ;
Les équipes sont petites et ont l’air soudées et de bien communiquer entre elles. La communication a l’air fluide, simple, efficace ;
Les équipes s’organisent comme elles le souhaitent et ont l’air de s’organiser de manière efficace ;
La présence d’un Product Owner dans la majorité des équipes semble jouer pour beaucoup à l’organisation de l’effort et au maintien de la qualité applicative ;
Les individus ont l’air épanouis et de prendre plaisir à leur travail ;
Il y a un climat général de confiance entre les équipes et apparemment avec la Direction du Numérique qui laisse aux équipe l’autonomie nécessaire.
En plus de cela, la pratique des foires hebdomadaires (30 minutes par semaine d’ouverture aux demandes en présentiel) semble être bien rodée, canalise les demandes et évite les tractations à la machine à café.
Les personnes reviennent des foires avec un besoin clarifié.
On refuse les demandes qui ne bénéficient pas à toutes les chaines ; les trucs dégueulasses ils les gèrent de leur côté.
Si nous devions donner un premier conseil général, ça serait celui de préserver, encourager et protéger tous ces morceaux de contextes techniques, organisationnels et humains qui mènent mécaniquement à un service rendu de qualité.
Il s’agit de l’équipe avec laquelle nous avons passé la majorité de notre temps.
Au 9 juillet 2017, la stack est basée sur node@6 et a pour objectif de suivre son cycle Long-term Support (LTS).
Le langage JavaScript est utilisé à hauteur de l’implémentation supportée par Node.
Le choix technologique initial des services API étaient basés sur LoopBack et MongoDB.
Après moults difficultés et frustrations, l’équipe s’est recentrée sur le duo Express et PostgreSQL.
L’équipe API met à disposition plusieurs modules NodeJS sur GitLab.
Ces modules sont préfixés par rf- par convention.
Leur usage en dehors des projets de l’équipe est inconnu.
| Succès |
|
| Frictions |
|
| Opportunités |
|
On veut réduire le temps de mise en production.
Il existe une dizaine de web services avec comme objectif de distribuer la donnée au plus de monde possible au sein de Radio France.
Les services sont déployés 5 à 10 fois par semaine avec Capistrano, tandis que le provisioning et l’instantiation sont effectués avec Terraform et Puppet. L’infrastructure gère environ 100 millions de requêtes par jour avec un uptime de 100%.
On veut être résilient à tout type de pannes.
La structure de données de l’API a pour vocation à rester rétrocompatible afin de limiter la maintenance des consommateurs de l’API. Une surcouche de l’API — la Public API — est consommée par les services mobiles. Cette dernière diffère légèrement de l’API privée car elle expose moins de champs et a recours à la spécification JSON API.
| Succès |
|
| Frictions |
|
| Opportunités |
|
L’API de recherche textuelle au sein des contenus se base sur ElasticSearch.
Elle est notamment utilisée pour les recommandations d’articles (via la fonctionnalité more_like_this), l’autocomplétion
On n’est pas très bon sur la recherche client.
| Frictions |
|
| Opportunités |
|
Il y a 2 ans, on a commencé la nouvelle infrastructure from scratch. Maintenant on s’ennuie presque — beaucoup de micro-tâches, souvent de l’ordre d’une journée ou moins.
|
Actions et envies priorisées
dtc innovation et l’équipe API ont fait émerger et priorisé une liste d’actions à mener autour des projets de l’équipe. Cette liste exhaustive d’envies est formulée en annexe de ce document. |
Concernant les limitations de rf-pg-connector, David Bruant a passé un peu de temps avec Florian de l’équipe API.
La conclusion semble être que le problème est identifié et qu’il faut juste passer du temps à le résoudre.
Afin de rendre la transition douce, il est recommandé d’épingler les numéros de versions de dépendance et de procéder la transition de ses consommateurs un par un. Florian a indiqué que cette procédure est connue et a déjà été appliquée.
| Opportunités |
|
Concernant les requêtes SQL, il est conseillé d’utiliser un query builder ou un autre. Cela augmenterait la lisibilité du code SQL qui se cache à l’intérieur du JavaScript.
Nous avons vu que le module node-sql ne supporte pas les LATERAL JOIN.
Apparemment, le choix des LATERAL JOIN (plutôt que des requêtes imbriquées) a été fait sur un conseil d’un expert pour raison de performances.
| Opportunités |
|
Florian a évoqué un questionnement sur le fait d’avoir du SQL à 3 endroits (rf-pg-connector, rf-models et dans chaque modèle).
Ce choix a l’air raisonnable.
Ces 3 endroits correspondent à 3 strates de spécificités qu’il n’est pas mauvais de garder séparés.
Les équipes chaînes gèrent un back-end écrit en PHP avec le framework Symfony. Un SDK incubé par l'équipe back-end abstrait les appels à l’API. Chaque chaîne gère surcharge les composants du SDK pour gérer leurs cas spécifiques d’interprétation des données.
| Succès |
|
| Frictions |
|
La recherche, c’est encore un autre format.
On voudrait que la structure des objets soit la même à tout moment.
Chaque chaîne gère leur front-end selon les affinités et compétences en présence. Nos discussions ont fait émerger un problème commun concernant la gestion du code JavaScript côté client. Chaque site de chaîne a son processus de build, ses outils, ses habitudes, ses façons de faire le JavaScript front-end. Ceci se traduit naturellement en beaucoup de travail dupliqué et difficilement réutilisé.
Le front-end, c’est le cœur de la problématique.
Un conseil ici serait d’avoir une équipe transverse spécifique sur à sujets, de la même manière qu’il existe une équipe transverse sur le framework PHP qui interroge l’API interne. Il existe l'équipe cockpit qui produit des composants transverses comme le player multimédia. Notre compréhension à ce stade est que cette équipe ne fait que créer et maintenir quelques composants front-end réutilisés par tous les sites.
On voudrait avoir des briques fonctionnelles isolées. On a fait ça dans le rush et on n’en a peut-être pas assez parlé.
| Opportunités |
|
Cette équipe a été montée il y a environ un an pour remplacer l’API Radio (un composant parmi ceux gérés par l’équipe API) — API en charge de normaliser les données collectées depuis le SI métier. Cet effort a été engagé pour mettre fin aux problèmes liés l’accumulation de rustines successives et pour distribuer la connaissance des règles métier jusque là contenue dans la tête d’une personne.
Une des caractéristiques de cette équipe est d’avoir deux Product Owner : un à la Direction du Numérique et un au Service Informatique. Une intention claire est de rapprocher la Direction du Numérique et le SI par la pratique.
C’est le premier projet en coopération avec l’équipe informatique basée de l’autre côté de la ligne de RER.
Tout le monde travaille sur tout. Tout le monde fait le support. Nous avons des rituels de partage de connaissance.
Maziar sait bien s’entourer et il nous fait confiance.
Le module rf-pubsub a été mentionné à quelques reprises.
Notamment l’effort de publication d’un module additionnel — un wrapper — pour le promisifier.
| Frictions |
|
| Opportunités |
|
Beaucoup de sujets ont été évoqués, dont celui d’une charte graphique (voire d’un styleguide) en cours de réalisation. Ce sujet a aussi été évoqué par au moins deux équipes chaînes.
Les designers sont embarqué·e·s dans les équipes chaînes en fonction des demandes et de la charge de travail. Une personne peut travailler en alternance pour l’équipe Culture et France Bleu, par exemple.
| Succès |
|
| Frictions |
|
| Opportunités |
|
L’équipe mobile est située dans un bureau à part. Elle est constituée de développeurs iOS et Android mais aussi de Product Managers.
Leurs interactions avec l’API Radio France se fait via la Public API, quasi exclusivement en consommation.
La seule API en POST qui soit utilisée n’est par ailleurs par gérée par l’équipe API.
Normalement on a une doc de l’API mais je ne sais plus où elle est.
Notre documentation c’est le SDK qu’on s’est fait. Il reflète notre besoin. Quand on a une question va voir l’équipe API.
Des problèmes de performance sur une route de l’API staging (40 à 50 secondes d’attente) ont obligé les développeurs à changer leurs valeurs de timeout et à opter pour cibler l’environnement de production à la place. Ils ne savent pas d’où vient le problème ni s’il a été réglé.
On trouvait ça mieux de tester en production. C’est plus parlant.
Il parait qu’ils refont la documentation ; elle est finie ?
On essaie de rattraper le delta entre API privée et Public API.
| Frictions |
|
| Opportunités |
|
Nous entamons une discussion après avoir lu le mot documentation sur un post-it affiché sur un tableau blanc.
Les gens de la technique, ils ne viennent pas nous voir.
J’ai plein de données analytics que j’ai du mal à récupérer.
| Frictions |
|
| Opportunités |
|
Radio France envisage de mettre à disposition une Open API à des personnes tierces. Elle serait une version dérivée de la Public API — cette dernière étant destinée aux sites et applications Radio France.
Cette envie s’inscrit dans la compréhension des usages d’écoute et de consommation des flux de Radio France. Un des objectifs est de pouvoir soutenir les mouvements de désintermédiation et d’innovation, mais aussi d’anticiper les effets de la Loi République Numérique — on peut en effet imaginer qu’à terme les données courantes de Radio France soient considérées comme une information publique.
Nous voulons mutualiser les coûts et les ressources entre acteurs.
L’ouverture de l’API bénéficierait également à Radio France en faisant émerger les données cachées, en facilitant la réutilisation de leurs données tout en devenant un aimant pour repérer et attirer les talents. L’émergence de réutilisations et de contributions (notamment de traduction) apporteraient également des éléments de réflexion à la stratégie produit de Radio France.
| Succès |
|
| Frictions |
|
| Opportunités |
|
Il ne faut pas perdre de vue la vision globale.
Mon challenge c’est de faire travailler les gens ensemble.
Être dans le mouvement, maintenir la dynamique pour ne pas devenir une startup vieillissante.
L’enjeu se situe également côté produit, sinon il n’y a pas d’enjeu technique.
L’équipe API constitue une pierre angulaire du succès de la stratégie de la Direction du Numérique mise en œuvre il y a de cela deux ans. Sa réussite tient à la confiance portée dans l’équipe, à des recrutements de qualité, au rôle des Product Owners et à la présence d’équipes connexes telles que l’infrastructure, back-office et Zone 51.
Les enjeux sont multiples :
se remettre dans une situation de challenge pour réunir et motiver les équipes à aller plus loin ensemble ;
réitérer le succès technique de l’API au niveau du langage visuel avec une plus grande diversité de métiers — UX, mobile, front-end ;
éviter le clivage client/fournisseur lié aux frontières dures établies par des postures.
Nous pensons que :
simplifier les strates d’accès à l’API (Open vs. interne) aidera à la maintenance, du code API et de ses consommateurs — ainsi que les interactions et relations afférantes ;
le typage transversal aidera à garantir la qualité des structures de données (schema.org, JSON-LD, Swagger, TypeScript/Flow) ;
la convergence styleguide/web/mobile aidera à mettre les équipes en position de collaboration multi-disciplinaire en vue de réaliser un objet commun — des entités Radio France solides dans et hors les murs, côté services et côté utilisateurs.
Le meilleur soutien et accompagnement que l’on puisse apporter serait de pairer à la réalisation de tâches/epics ciblées pour maintenir l’autonomie dont fait déjà preuve l’équipe API et les équipes afférantes.
Les sections suivantes découlent de la première journée de présence sur place, à savoir le jeudi 15 juin.
L’ensemble des actions ventilées ci-dessous a été présenté à l’équipe API qui les a ensuite priorisé en fonction de ses appétences et de ses intérêts.
Eslint : renforcer certaines pratiques via des règles additionnelles, voire la création de règles custom ;
Eslint : établir un package de configuration Radio France
Package rf-init — auditer ;
Package rf-pg-connector — auditer, passer en promesses, quid d’un redesign d’API pour permettre ;
Package rf-pg-connector — utilisation de template strings ou d’un query builder ? ;
Anticiper le passage en node@8 et ECMAScript 2016/2017 ;
Quid des consumers Symfony de l’API.
Documentation des concepts métier — glossaire, etc. ;
Public API : explorer l’aspect vocabulaire/ontologie pour rendre le contenu référençable hors du contexte Radio France (aka Linked Data) ;
Public API : comment l’utiliser dans différents cas d’accès à l’API (ex : WebExtension, WebHook, CI, WebApp, etc.) ;
Public API : quelle(s) stratégie(s) d’authentification ? ;
Public API : POURQUOI, QUI et COMMENT afin de bien designer le contenu et les exemples ;
Public API : quelle(s) stratégie(s) de documentation.
Quel retour sur investissement de tester en local vs. tester uniquement en intégration continue ?
Harmoniser la documentation des repos, des README notamment ;
Document d’architecture — remettre la main dessus, le rendre visible ;
Stratégie de partage de setup de machines — dans l’équipe API, leur entourage immédiat et éventuellement avec les autres équipes dev du plateau ;
Quid de la découvrabilité de l’API ;
Faire une review des requêtes ElasticSearch ;
Participer à des codes review — quelles pratiques faire émerger ?
Quid de la consistance des données — "greg" ne retournait pas de suggestions dans l’API autocomplete, un document retourné par ElasticSearch était en réalité manquant (pas de concept associé) ;
Quid du requêtage en pur SQL vs. assistance en JavaScript — mieux documenter l’intention de requêtes complexes notamment ;
Quel est le bus factor d’Éric ?
la prioritisation avec des post-it en début de deuxième journée ;
lecture transverse, juste et bienveillante de dtc innovation ;
idée des cliniques pour pairer sur des librairies Node ;
émergence d’un challenge sur les formats de représentation des données de l'Open API ;
émergence d’un challenge sur le duo documentation/schéma des APIs (avis partagé avec Zone 51) ;
émergence de l’opportunité d’open sourcer rf-init et rf-pubsub (considérer une organisation npm).