Un API pour exploiter les données de l'Assemblée nationale du Québec.
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 .
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.
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.
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.
Ce document peut contenir les champs suivants:
'ind.'
si indépendant)'M.'
ou 'Mme'
'm'
ou 'f'
Ce document peut contenir les champs suivants:
volume.numéro
, ex.: 42.122
)législature.session
, ex.: 39.2
)vendredi
)2012-06-12T04:00:00.000Z
)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:
\n
district
du député si celui-ci a changé de circonscription depuis (facultatif)party
du député si celui-ci a changé de parti depuis (facultatif)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.
/deputies : retourne un Array
contenant l'ensemble des députés. Exemple.
Filtres:
true
ou 1
pour "vrai", toute autre valeur étant fausse.'*'
(casse non significative).'*'
(casse non significative). Exemple./deputies/:idDep : retourne le député correspondant à l'identifiant :idDep
, ou un code 404 si l'identifiant n'existe pas. Exemple.
Filtres: aucun.
/deputies/:idDep/interventions : retourne un Array
contenant l'ensemble des interventions du député identifié par :idDep
. Exemple.
Filtres:
'*'
(casse non significative).'*'
(casse non significative).'*'
(casse non significative)./deputies/:idDep/interventions/:idInt : retourne l'intervention correspondant à l'identifiant :idInt
, ou un code 404 si l'identifiant n'existe pas ou s'il n'est pas associé au député identifié par :idDep
. Exemple.
Filtres: aucun.
/meetings : retourne un Array
contenant l'ensemble des séances. Exemple.
Filtres:
législature.session
). Exemple./meetings/:idMeeting : retourne la séance correspondant à l'identifiant :idMeeting
, ou un code 404 si l'identifiant n'existe pas. Exemple.
Filtres: aucun.
/meetings/:idMeeting/interventions : retourne un Array
contenant l'ensemble des interventions de la séance identifiée par :idMeeting
. Exemple.
Filtres:
'*'
(casse non significative).'*'
(casse non significative).'*'
(casse non significative)./meetings/:idMeeting/interventions/:idInt : retourne l'intervention correspondant à l'identifiant :idInt
, ou un code 404 si l'identifiant n'existe pas ou s'il n'est pas associé à la séance identifiée par :idMeeting
. Exemple.
Filtres: aucun.
/interventions : retourne un Array
contenant l'ensemble des interventions. Exemple.
Filtres:
'*'
(casse non significative).'*'
(casse non significative).'*'
(casse non significative)./interventions/:idInt : retourne l'intervention correspondant à l'identifiant :idInt
, ou un code 404 si l'identifiant n'existe pas. Exemple.
Filtres: aucun.
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):
'-'
) devant le nom du champ. Se référer à la documentation sur les types d'objets pour voir le nom des champs.0
).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:
subject
et subtitle
comporte quelques problèmes. J'aimerais améliorer le tout dans une future version.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.
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.