Ontwikkelaars / API-referentie

Poll API

v3

Integraties die voor de vorige StrawPoll API zijn gebouwd, blijven werken. Zo verhoudt v3 zich tot formulieren.

Basis-URL
https://api.strawpoll.com/v3
Specificatie
OpenAPI 3

Poll API v3 blijft werken

Code die je voor de vorige StrawPoll API hebt geschreven, blijft draaien. De v3-endpoints zijn ongewijzigd bereikbaar op https://api.strawpoll.com/v3 (en https://strawpoll.com/api/v3), accepteren dezelfde X-API-Key-header en spreken dezelfde JSON, zoals beschreven in de v3-OpenAPI-specificatie.

Gebruik voor nieuwe projecten de Forms API (v4): die ondersteunt elk vraagtype, concepten, reacties en uitnodigingen. v3 krijgt nog wel fixes, maar geen nieuwe functies.

Wat een v3-poll nu is

Elke v3-poll is een formulier met één vraag:

v3-typeFormuliersection
multiple_choice met text-optiesmultiple_choice
multiple_choice met image-optiespicture_choice
ranked_choiceranked_choice
meeting met date- en time_range-optiesmeeting

De id van een poll is de slug van het formulier en optie-id’s zijn choice-id’s, dus je kunt beide API’s door elkaar gebruiken: maak een poll via v3 en lees de reacties via v4, of andersom. require_voter_names voegt een contactsection toe die naar een naam vraagt.

Formulieren met meer dan één vraag kun je via v3 lezen; v3 toont dan de eerste vraag. Wijzigen via v3 wordt geweigerd met 409 unsupported_form, zodat v3 nooit vragen verwijdert die het niet ziet. Gebruik daarvoor v4.

Instellingen

poll_configFormulierinstelling
deadline_atclosesAt
duplication_checking: ip, session, invite, noneresponseDuplicateCheck: ip, session, code, none
results_visibility: always, after_vote, after_deadline, neverresultsVisibility: public, public_after_response, public_after_close, private
edit_vote_permissions: admin, admin_voter, voter, nobodyeditResponsePermissions: admin, admin_own_responses, own_responses, nobody
hide_participantsresponsesVisibility: private
allow_commentsallowComments, met openbare opmerkingen
allow_vpn_usershet omgekeerde van blockVPNUsers
force_appearance: light, dark, autohet lichte of donkere StrawPoll-thema, of geen
is_multiple_choice, multiple_choice_min, multiple_choice_maxhetzelfde, waarbij 0 geen limiet betekent
allow_other_optioneigen antwoorden
randomize_optionsopties in willekeurige volgorde
allow_indeterminate“desnoods”-antwoorden in planningspolls
require_voter_nameseen naamvraag; altijd aan bij planningspolls

PUT/polls/{id} houdt elke instelling die je weglaat uit poll_config, en houdt de stemmen van opties waarvan je de id terugstuurt.

Formulieren die in de editor zijn ingesteld, kunnen controles gebruiken waar v3 geen woord voor heeft. Die verschijnen als de dichtstbijzijnde v3-waarde: een naamcontrole als session, een e-mailcontrole als invite.

Verschillen die je moet kennen

  • Polls worden direct gepubliceerd. v3 had geen concepten. Wijzigingen via PUT staan meteen live; een concept dat in de editor openstaat, blijft ongemoeid.
  • is_private is altijd true. Op het nieuwe platform worden polls nooit openbaar vermeld.
  • Resultaten. poll_votes zijn 1 (gekozen of ja), 0 (niet gekozen of nee), 2 (desnoods) en null (niet beantwoord). Bij ranked_choice zijn ze de plaats die de stemmer de optie gaf, waarbij 1 de eerste is. poll_participants is leeg, tenzij namen openbaar zijn of de poll van jou is. Resultaten die je nog niet mag zien, antwoorden met 403 results_hidden.
  • Eigen antwoorden verschijnen als extra opties met is_write_in: true.
  • Opmerkingen zijn notities die stemmers bij hun stem achterlaten. Je kunt ze opvragen, lezen en (als eigenaar van de poll) verwijderen; POST/comments en PUT/comments/{id} antwoorden met 501.
  • Gebruikers. Er zijn geen openbare profielen: /users/@me (of je eigen id) werkt, elke andere gebruiker geeft 404. username is null en user_meta bevat alleen standaardwaarden. PATCH/users/@me wijzigt displayname.
  • Media. POST/upload accepteert afbeeldingen (JPEG, PNG, GIF of WebP, maximaal 5 MB). Video’s en media van YouTube en Giphy worden niet ondersteund, dus POST/media en PUT/media/{id} antwoorden met 501. DELETE/media/{id} weigert afbeeldingen die een poll nog toont.
  • Tellers die niet meer bestaan, zoals view_count en punten, zijn 0.
  • Fouten zijn JSON-objecten met error en code, en dezelfde limieten gelden als voor v4.

Je bestaande sleutels

Sleutels van het vorige platform blijven werken zodra je account is overgezet. Je kunt ook nieuwe sleutels maken in Instellingen → API-sleutels; die werken voor v3 en v4.