assnatapi

Un API pour exploiter les données de l'Assemblée nationale du Québec.

View the Project on GitHub PuerkitoBio/assnatapi

assnatapi - un API pour l'Assemblée nationale du Québec

Présentation

Un API de type REST pour permettre l'exploitation par programmation des données de l'Assemblée nationale du Québec.

L'API se trouve à l'adresse http://assnatapi.jit.su .

Pourquoi?

Le site web de l'Assemblée nationale contient toutes les transcriptions textuelles des débats et des travaux des différentes commissions au parlement. Le tout est cependant dans un format HTML pratique pour un humain mais moins pour une machine. Des applications - mobiles ou non - et sites web pourraient être développés pour mieux présenter ces données et offrir différents services aux citoyen(nes) et professionnel(le)s de l'information. Cependant, en l'absence d'un format convivial à la programmation, c'est une tâche peu triviale.

Cet API (interface de programmation d'application), qui repose sur les données publiques, extraites du site officiel de l'Assemblée nationale du Québec et structurées en une base de données documentaire MongoDB, vise à combler cette lacune par rapport aux données ouvertes (open data) - à tout le moins du point de vue exploitation, l'aspect conditions d'utilisation étant hors de notre contrôle - dans cette institution au coeur de notre démocratie.

Ce référentiel GitHub contient le code du serveur web répondant aux requêtes pour l'API seulement. Le code du programme qui extrait les données du site de l'Assemblée et les sauvegarde de façon structurée dans la base de données n'est pas encore déposé publiquement. Il le sera éventuellement, quand j'aurai terminé l'automatisation complète des tâches.

Vous pouvez supporter le développement du projet par un don sur la page d'accueil du site.

Statut de l'API

La version actuelle - 0.1.x - devrait être considérée comme une version alpha. L'idée est de la rendre disponible, tâter l'intérêt pour l'API, recevoir les commentaires et suggestions, les problèmes rencontrés, et la faire évoluer à partir de cette rétroaction. La page GitHub issues du projet devrait être utilisée pour ces communications. À l'inverse, je publierai les évolutions du projet sur mon fil Twitter, sous le hashtag #assnatapi. La période de pause parlementaire estivale permet l'expérimentation de l'API en toute quiétude afin de préparer le tout pour une version stable à la rentrée.

Tout peut donc être appelé à changer en cette jeune version, les URL, les noms des champs, etc. Et pour le moment, seuls les travaux du mois de juin 2012 de la 39ème législature, 2ème session sont offerts par l'API. D'autres seront ajoutés sous peu.

Référence et exemples

Trois types de documents peuvent être retournés par l'API. Les champs sont en anglais pour de simples questions pratiques, les accents et les mots français se prêtant moins bien à une nomenclature pour un langage de programmation, et mélanger les mots clefs des langages (en anglais, tels que for, if, etc.) avec des noms de variables ou de propriétés en français n'est pas naturel à la lecture du code.

deputy: un document représentant un député à l'Assemblée nationale.

Ce document peut contenir les champs suivants:

meeting: un document représentant une séance de travail à l'Assemblée nationale.

Ce document peut contenir les champs suivants:

intervention: un document représentant une intervention lors d'une séance.

Il peut s'agir d'une intervention d'un député, ou d'un officiel de l'assemblée (président, vice-président, etc.). Bien que l'officiel soit un député élu, comme il ne s'exprime pas en tant que député lorsqu'il remplit un tel rôle, l'intervention n'est pas rattachée à ce député. Idem pour les interventions anonymes ("Des voix" ou "Une voix", par exemple). Ce document peut contenir les champs suivants:

Les routes et les paramètres

Comme l'API ne permet que de la consultation, la seule méthode HTTP permise pour chaque route est un 'GET'. Tous les résultats sont sous le format JSON. Chaque route qui retourne un Array peut supporter un ou plusieurs filtres (critères de recherche), de même qu'un tri, une limite d'enregistrements retournés, et un nombre d'enregistrements à sauter. Plus d'informations sur le tri, la limite et le saut dans un instant. Les filtres, le tri, la limite et le saut sont spécifiés par chaîne d'interrogation (query string, soit la portion de l'URL qui suit un '?') et sont séparés les uns des autres par le caractère '&'.

Un outil comme curl peut être utilisé pour tester l'API et vérifier les résultats retournés, mais comme il ne s'agit que de 'GET', il est aussi possible de faire les appels directement depuis le fureteur Web, via la barre d'adresse.

Tel que promis, un mot sur le tri, la limite et le saut, qui peuvent s'appliquer à toutes les routes retournant un ensemble d'enregistrements (un Array). En gras, le nom de la clef à utiliser dans la chaîne d'interrogation (query string):

Journal des changements (changelog)

Pistes d'évolution

Rien de coulé dans le béton pour le moment, mais ces points sont déjà investigués et devraient être des ajouts réalistes dans une future version:

Détails techniques et style de code

Le serveur web utilise les technologies suivantes, toutes en logiciel libre à moins d'indication contraire:

Pour le style du code, j'en parle puisque ça a généré une mini-controverse dans le monde javascript et c'est important à savoir si vous souhaitez collaborer au projet, je n'utilise pas de point-virgule dans mon code, laissant l'ASI (automatic semicolon insertion) faire son travail, et j'utilise JSHint pour valider la qualité du code, qui est plus flexible que JSLint de Crockford (il permet entre autre l'écriture sans ';'). À noter par contre que je n'utilise pas le style virgule en début de ligne popularisé surtout par Isaac Schlueter sur npm.

Licence

Le code source est offert sous la licence de logiciel MIT. Les données de l'Assemblée nationale, cependant, demeurent probablement limitées par les conditions d'utilisation originales de l'Assemblée.