Agor API : le couteau suisse des systèmes de votes

API

Cela fait quelques semaines que nous bouillonnons d’impatience à l’idée de vous présenter notre dernière création : Agor API. C’est une solution pour intégrer consultations, votes et sondages sur votre site web ou dans votre logiciel.

C’est quoi une API ?

Une API, ou Application Programming Interface, est un ensemble de fonctions que des développeurs (comme nous) ont crées pour que d’autres développeurs puissent utiliser simplement des outils, des méthodes et des algorithmes potentiellement complexes.

L’objectif est de fournir une porte d’accès à une fonctionnalité en cachant les détails de sa mise en œuvre. L’API est donc une interface « boite à outils » qui offre des services à d’autres logiciels. Vous pouvez ainsi profiter de toutes ces fonctions que nous avons conçu pour vous, par un simple appel à AgorAPI.

Pourquoi ce produit ?

Cela fait bientôt 2 ans que vous réalisez des votes, des consultations et des sondages sur notre application Slack. Avec près de 60 000 utilisateurs et 35 000 consultations effectuées, nous avons entendu votre besoin croissant d’outils de votes simples et rapides à mettre en place.

API - Slack logo

Nous sommes convaincus de l’intérêt des processus démocratiques et particulièrement des systèmes de votes alternatifs. Nous avons ainsi travaillé sans relâche ces derniers mois pour vous proposer AgorAPI (Agora Polling Interface).

Les applications sont multiples, voici quelques-une de nos idées :

Cette liste est bien évidemment non exhaustive. Votre imagination est la seule limite. Nous avons hâte de voir ce que vous allez réussir à créer avec AgorAPI !

Elle est disponible en accès anticipé à partir du mercredi 14 Juin 2017. Vous êtes tous invité à la tester, à nous proposer des améliorations. Et à identifier les imprécisions qui subsistent dans le Guide et la Documentation. L’accès anticipé devrait durer jusqu’à la fin de l’été. Nous améliorerons notre service tout au long de cette période transitoire.

Nous comptons sur vous ! Plus vous nous donnerez de retours, meilleure sera AgorAPI à son lancement officiel !

Le couteau Suisse des systèmes de vote

Lors de la conception d’AgorAPI, nous avions l’objectif de créer un outil complet et flexible. Aujourd’hui, AgorAPI vous permet d’utiliser le système de vote adapté à votre consultation : le vote majoritaire classique (le choix ayant recueilli le plus de voix l’emporte) ou la méthode Condorcet (vote nuancé amenant un résultat consensuel).

Voici un résumé des fonctions à mettre en place lors de votre développement pour utiliser ces méthodes de vote dans vos consultations:

Authentification

Pour assurer sécurité et confidentialité, toutes les requêtes à l’API sont identifiées au moyen d’un jeton, autorisant un accès complet à vos données. Vous devez donc faire en sorte de garder vos jetons secrets !

Création d’une consultation

En envoyant une requête comprenant l’intitulé et les différents choix de la consultation, vous générez des identifiants (PXXX pour la consultation, CXXX pour les choix qui lui sont rattachés). Ces identifiants vous permettront de gérer toutes les interactions avec la consultation (votes, ajout de choix, clôture …)

Vote

Pour voter, il suffit d’envoyer une requête avec les identifiants PXXX de la consultation et CXXX du choix sélectionné. Il est possible de voter pour plusieurs choix (vote nuancé), en envoyant la liste des choix souhaités et leurs rangs de préférences respectifs (exemple : C003 en rang 1, C006 en rang 2, C002 en rang 3)

Affichage des résultats

Le résultat comprend la liste des choix de la consultation, triés par ordre décroissant de leurs scores. Vous pouvez ensuite générer des diagrammes de résultats, afin d’illustrer visuellement l’issue de la consultation.

Gestion des utilisateurs

Si l’application qui utilise AgorAPI comporte des utilisateurs, l’API permet d’associer chaque vote à un utilisateur ou encore de s’assurer que chaque utilisateur n’a voté qu’une fois.

De nombreuses options supplémentaires s’offrent à vous. De l’insertion/modification des choix en cours de consultation jusqu’à l’anonymat des votes, nous avons implémenté tout ce qui vous permettra de personnaliser votre consultation. Vous pouvez consulter le Guide d’utilisation ainsi que la documentation détaillée pour apprendre à exploiter toute la puissance d’AgorAPI dans vos projets.

Et ce n’est pas fini ! Nous élargirons prochainement le panel des systèmes de votes disponibles pour que chacune de vos consultations soit réalisée avec la méthode la plus adaptée.

Exemple pratique : Module de vote intégré à un site web

Si vous êtes arrivé jusqu’ici, il est fort probable que vous soyez intéressé par cet exemple.

Ce tutoriel de 10 minutes permet une intégration très rapide du vote Condorcet sur votre site web.

Prérequis :

  • Avoir PHP 5.4 CLI ou version supérieure installé sur votre machine.
  • Être inscrit à AgorAPI et avoir créé une clé d’accès à l’API sur votre espace personnel.

Tout d’abord, pour simplifier la manœuvre, commencez par paramétrer la variable shell API_TOKEN en remplaçant <MyApiKey> par votre clé d’accès dans un terminal :

API_TOKEN=&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;MyApiKey&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;

Vérifiez ensuite le fonctionnement de votre clef en lançant cette requête :

curl -i -H "Accept: application/json" -H "Content-type: application/json" \
     -X GET "https://api.open-agora.com/info?api_token=$API_TOKEN"

Cette commande devrait vous renvoyer la description de votre clef, ainsi que le nombre de crédits utilisés et restants.

Vous pouvez désormais créer un vote ! Lancez la requête ci-dessous en remplaçant Ma question par l’intitulé de votre consultation. Et premier choix, second choix et troisième choix par les différentes options que vous proposerez comme choix de vote (vous pouvez en rajouter).

curl -i -H "Accept: application/json" -H "Content-type: application/json" \
     -X POST "https://api.open-agora.com/polls/with-choices?api_token=$API_TOKEN" \
     -d '{"title": "Ma question", "choices": [{"label": "premier choix"}, {"label": "second choix"}, {"label": "troisième choix"}]}'

Cette requête devrait renvoyer un contenu JSON avec la valeur « id » en première ligne :

"id": "PXXXXXXXXX"

Notez cette valeur dans un coin, elle vous servira pour accéder à votre consultation à partir du navigateur.
Vous avez désormais créer votre consultation, et vous êtes prêt à l’intégrer sur votre site.

Pour commencer :

Téléchargez et décompressez ces fichiers : poll_example_FILES.zip

Éditez ensuite api.ini dans le dossier OA, et remplacez <MyApiKey> par votre clef d’accès.

[client]
base_url = https://api.open-agora.com
token =&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;MyApiKey&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;

Vous pouvez sauvegarder api.ini et placer tous les fichiers dans le dossier ou sur le serveur de votre choix (en conservant api.ini et CurlClient.php dans le dossier OA).
Si vous voulez tester le fonctionnement en local,  rendez-vous dans le dossier en question à partir du terminal. Lancez un serveur php à la source :

php -S localhost:8888

Vous devez ensuite accéder à la page vote_index.php via votre navigateur. Cette page va permettre aux personnes qui s’y connectent de voter et de voir l’état actuel des votes effectués. L’identifiant du poll (le id que vous avez récupéré un peu plus haut) doit être passé en paramètre lors de la saisie de l’URL : http://votre-url-de-vote.domain/vote_index.php?id= (ou localhost:8888/vote_index.php?id= si vous êtes en local)

Voila, vous avez créé une interface de vote Condorcet fonctionnelle !

Vous pourrez bientôt consulter notre Github pour accéder à des exemples comportant davantage d’options (changer de système de vote, ajouter, modifier et supprimer des consultations ou des choix directement dans votre navigateur).


A propos d’Open Agora

Consultations nuancées et ciblées

Les solutions Open Agora permettent de collecter des opinions riches et d’atteindre facilement le consensus

Partager / Share this...