Poll API v3 – StrawPoll

La Poll API v3 continue de fonctionner

Le code écrit pour l’ancienne API StrawPoll continue de tourner. Les endpoints v3 restent servis à l’identique sur https://api.strawpoll.com/v3 (et https://strawpoll.com/api/v3), acceptent le même en-tête X-API-Key et parlent le même JSON, comme décrit dans la spécification OpenAPI v3.

Pour les nouveaux projets, utilisez la Forms API (v4) : elle couvre tous les types de questions, ainsi que les brouillons, les réponses et les invitations. La v3 recevra encore des correctifs, mais plus de nouvelles fonctionnalités.

Ce qu’est devenu un sondage v3

Chaque sondage v3 est un formulaire à une seule question :

`type` v3	Section du formulaire
`multiple_choice` avec des options `text`	`multiple_choice`
`multiple_choice` avec des options `image`	`picture_choice`
`ranked_choice`	`ranked_choice`
`meeting` avec des options `date` et `time_range`	`meeting`

L’id d’un sondage est le slug du formulaire, et les identifiants d’options sont des identifiants de choices. Vous pouvez donc combiner les deux API : créer un sondage via la v3 et lire ses réponses via la v4, ou l’inverse. require_voter_names ajoute une section de coordonnées qui demande un nom.

Les formulaires de plusieurs questions peuvent être lus via la v3, qui affiche leur première question. Toute modification via la v3 est refusée avec 409 unsupported_form : la v3 ne supprime ainsi jamais des questions qu’elle ne voit pas. Utilisez la v4 pour ces formulaires.

Paramètres

`poll_config`	Paramètre du formulaire
`deadline_at`	`closesAt`
`duplication_checking`: `ip`, `session`, `invite`, `none`	`responseDuplicateCheck`: `ip`, `session`, `code`, `none`
`results_visibility`: `always`, `after_vote`, `after_deadline`, `never`	`resultsVisibility`: `public`, `public_after_response`, `public_after_close`, `private`
`edit_vote_permissions`: `admin`, `admin_voter`, `voter`, `nobody`	`editResponsePermissions`: `admin`, `admin_own_responses`, `own_responses`, `nobody`
`hide_participants`	`responsesVisibility: private`
`allow_comments`	`allowComments`, avec des commentaires publics
`allow_vpn_users`	l’inverse de `blockVPNUsers`
`force_appearance`: `light`, `dark`, `auto`	le thème StrawPoll clair ou sombre, ou aucun
`is_multiple_choice`, `multiple_choice_min`, `multiple_choice_max`	identiques, `0` signifiant aucune limite
`allow_other_option`	réponses libres
`randomize_options`	options mélangées
`allow_indeterminate`	réponses « si nécessaire » dans les sondages de réunion
`require_voter_names`	une question sur le nom ; toujours active pour les sondages de réunion

PUT/polls/{id} conserve chaque paramètre que vous omettez dans poll_config, ainsi que les votes des options dont vous renvoyez l’id.

Les formulaires configurés dans l’éditeur peuvent utiliser des contrôles que la v3 ne connaît pas. Ils apparaissent sous la valeur v3 la plus proche : un contrôle par nom comme session, un contrôle par e-mail comme invite.

Les différences à connaître

Les sondages sont publiés immédiatement. La v3 n’avait pas de brouillons. Les modifications via PUT sont en ligne tout de suite ; un brouillon ouvert dans l’éditeur n’est pas touché.
is_private vaut toujours true. Sur la nouvelle plateforme, les sondages ne sont jamais listés publiquement.
Résultats. poll_votes vaut 1 (choisi ou oui), 0 (non choisi ou non), 2 (si nécessaire) et null (sans réponse). Pour ranked_choice, c’est la place que le participant a donnée à l’option, 1 étant la première. poll_participants est vide, sauf si les noms sont publics ou si le sondage vous appartient. Les résultats que vous n’êtes pas encore autorisé à voir répondent 403 results_hidden.
Les réponses libres apparaissent comme des options supplémentaires avec is_write_in: true.
Les commentaires sont des notes que les participants laissent avec leur vote. Vous pouvez les lister, les lire et (en tant que propriétaire du sondage) les supprimer ; POST/comments et PUT/comments/{id} répondent 501.
Utilisateurs. Il n’y a pas de profils publics : /users/@me (ou votre propre id) fonctionne, tout autre utilisateur renvoie 404. username vaut null et user_meta ne contient que des valeurs par défaut. PATCH/users/@me modifie displayname.
Médias. POST/upload accepte les images (JPEG, PNG, GIF ou WebP, jusqu’à 5 Mo). Les vidéos et les médias YouTube et Giphy ne sont pas pris en charge : POST/media et PUT/media/{id} répondent donc 501. DELETE/media/{id} refuse les images encore affichées par un sondage.
Les compteurs qui n’existent plus, comme view_count et les points, valent 0.
Les erreurs sont des objets JSON avec error et code, et les mêmes limites de débit s’appliquent que pour la v4.

Vos clés existantes

Les clés de l’ancienne plateforme continuent de fonctionner une fois votre compte migré. Vous pouvez aussi créer de nouvelles clés dans Paramètres → Clés API ; elles fonctionnent pour la v3 comme pour la v4.