Poll API v3 – StrawPoll

Die Poll API v3 funktioniert weiter

Code für die bisherige StrawPoll-API läuft weiter. Die v3-Endpunkte sind unverändert unter https://api.strawpoll.com/v3 (und https://strawpoll.com/api/v3) erreichbar, nehmen denselben X-API-Key-Header an und sprechen dasselbe JSON, wie in der v3-OpenAPI-Spezifikation beschrieben.

Neue Projekte sollten die Forms API (v4) nutzen: Sie deckt jeden Fragetyp ab, dazu Entwürfe, Antworten und Einladungen. v3 bekommt weiterhin Fehlerbehebungen, aber keine neuen Funktionen.

Was eine v3-Umfrage heute ist

Jede v3-Umfrage ist ein Formular mit einer Frage:

v3-`type`	Formular-Section
`multiple_choice` mit `text`-Optionen	`multiple_choice`
`multiple_choice` mit `image`-Optionen	`picture_choice`
`ranked_choice`	`ranked_choice`
`meeting` mit `date`- und `time_range`-Optionen	`meeting`

Die id einer Umfrage ist der Slug des Formulars, und Options-IDs sind Choice-IDs. Du kannst also beide APIs mischen: eine Umfrage über v3 erstellen und ihre Antworten über v4 lesen, oder umgekehrt. require_voter_names fügt eine Kontakt-Section hinzu, die nach dem Namen fragt.

Formulare mit mehr als einer Frage lassen sich über v3 lesen, dann erscheint ihre erste Frage. Änderungen über v3 werden mit 409 unsupported_form abgelehnt. So entfernt v3 nie Fragen, die es nicht sieht. Nimm für solche Formulare v4.

Einstellungen

`poll_config`	Formulareinstellung
`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`, mit öffentlichen Kommentaren
`allow_vpn_users`	das Gegenteil von `blockVPNUsers`
`force_appearance`: `light`, `dark`, `auto`	das helle oder dunkle StrawPoll-Design oder keins
`is_multiple_choice`, `multiple_choice_min`, `multiple_choice_max`	dasselbe, wobei `0` kein Limit bedeutet
`allow_other_option`	eigene Antworten
`randomize_options`	gemischte Optionen
`allow_indeterminate`	„Notfalls“-Antworten in Terminumfragen
`require_voter_names`	eine Frage nach dem Namen; bei Terminumfragen immer aktiv

PUT/polls/{id} behält jede Einstellung, die du in poll_config weglässt, und behält die Stimmen der Optionen, deren id du zurückschickst.

Im Editor eingerichtete Formulare können Prüfungen nutzen, für die v3 kein Wort hat. Sie erscheinen als der nächstliegende v3-Wert: eine Namensprüfung als session, eine E-Mail-Prüfung als invite.

Unterschiede, die du kennen solltest

Umfragen werden sofort veröffentlicht. v3 kannte keine Entwürfe. Änderungen über PUT sind sofort live. Ein im Editor offener Entwurf bleibt unangetastet.
is_private ist immer true. Auf der neuen Plattform werden Umfragen nie öffentlich aufgelistet.
Ergebnisse. poll_votes sind 1 (gewählt oder Ja), 0 (nicht gewählt oder Nein), 2 (notfalls) und null (nicht beantwortet). Bei ranked_choice steht dort der Platz, den die Person der Option gegeben hat, wobei 1 der erste ist. poll_participants ist leer, außer die Namen sind öffentlich oder dir gehört die Umfrage. Ergebnisse, die du noch nicht sehen darfst, antworten mit 403 results_hidden.
Eigene Antworten erscheinen als zusätzliche Optionen mit is_write_in: true.
Kommentare sind Notizen, die Teilnehmende bei ihrer Stimme hinterlassen. Du kannst sie auflisten, lesen und (als Inhaber der Umfrage) löschen; POST/comments und PUT/comments/{id} antworten mit 501.
Nutzer. Öffentliche Profile gibt es nicht: /users/@me (oder deine eigene ID) funktioniert, jeder andere Nutzer ergibt 404. username ist null, und user_meta enthält nur Standardwerte. PATCH/users/@me ändert displayname.
Medien. POST/upload nimmt Bilder an (JPEG, PNG, GIF oder WebP, bis 5 MB). Videos sowie YouTube- und Giphy-Medien werden nicht unterstützt, daher antworten POST/media und PUT/media/{id} mit 501. DELETE/media/{id} lehnt Bilder ab, die eine Umfrage noch zeigt.
Zähler, die es nicht mehr gibt, etwa view_count und Punkte, sind 0.
Fehler sind JSON-Objekte mit error und code, und es gelten dieselben Ratenlimits wie für v4.

Deine bestehenden Schlüssel

Schlüssel von der bisherigen Plattform funktionieren weiter, sobald dein Konto umgezogen ist. Neue Schlüssel erstellst du unter Einstellungen → API-Schlüssel. Sie funktionieren für v3 und v4.