Sviluppatori / Riferimento API

Poll API

v3

Le integrazioni create per la precedente API di StrawPoll continuano a funzionare. Ecco come la v3 corrisponde ai moduli.

URL di base
https://api.strawpoll.com/v3
Specifica
OpenAPI 3

La Poll API v3 continua a funzionare

Il codice scritto per la precedente API di StrawPoll continua a funzionare. Gli endpoint v3 sono serviti senza modifiche su https://api.strawpoll.com/v3 (e https://strawpoll.com/api/v3), accettano la stessa intestazione X-API-Key e usano lo stesso JSON, come descritto nella specifica OpenAPI v3.

Per i nuovi progetti usa la Forms API (v4): copre tutti i tipi di domanda, oltre a bozze, risposte e inviti. La v3 riceverà correzioni, ma nessuna nuova funzionalità.

Cosa diventa oggi un sondaggio v3

Ogni sondaggio v3 è un modulo con una sola domanda:

type v3Sezione del modulo
multiple_choice con opzioni textmultiple_choice
multiple_choice con opzioni imagepicture_choice
ranked_choiceranked_choice
meeting con opzioni date e time_rangemeeting

L’id del sondaggio è lo slug del modulo e gli id delle opzioni sono id dei choices, quindi puoi combinare le due API: crea un sondaggio con la v3 e leggi le sue risposte con la v4, o viceversa. require_voter_names aggiunge una sezione di contatto che chiede un nome.

I moduli con più di una domanda si possono leggere con la v3, che mostra la loro prima domanda. Le modifiche tramite la v3 vengono rifiutate con 409 unsupported_form, così la v3 non elimina mai domande che non vede; per questi moduli usa la v4.

Impostazioni

poll_configImpostazione del modulo
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, con commenti pubblici
allow_vpn_usersl’opposto di blockVPNUsers
force_appearance: light, dark, autoil tema chiaro o scuro di StrawPoll, oppure nessuno
is_multiple_choice, multiple_choice_min, multiple_choice_maxgli stessi, dove 0 significa nessun limite
allow_other_optionrisposte libere
randomize_optionsopzioni in ordine casuale
allow_indeterminaterisposte «se necessario» nei sondaggi per riunioni
require_voter_namesuna domanda sul nome; sempre attiva nei sondaggi per riunioni

PUT/polls/{id} mantiene ogni impostazione che ometti da poll_config, e mantiene i voti delle opzioni di cui rinvii l’id.

I moduli configurati nell’editor possono usare controlli per cui la v3 non ha un valore. Vengono letti come il valore v3 più vicino: un controllo per nome come session, un controllo per email come invite.

Differenze da conoscere

  • I sondaggi vengono pubblicati subito. La v3 non aveva bozze. Le modifiche con PUT sono online immediatamente; una bozza aperta nell’editor non viene toccata.
  • is_private è sempre true. Sulla nuova piattaforma i sondaggi non vengono mai elencati pubblicamente.
  • Risultati. poll_votes vale 1 (scelta o sì), 0 (non scelta o no), 2 (se necessario) e null (nessuna risposta). Per ranked_choice è la posizione che il partecipante ha dato all’opzione, dove 1 è la prima. poll_participants è vuoto, a meno che i nomi siano pubblici o il sondaggio sia tuo. I risultati che non puoi ancora vedere rispondono 403 results_hidden.
  • Le risposte libere compaiono come opzioni aggiuntive con is_write_in: true.
  • I commenti sono note che i partecipanti lasciano con il loro voto. Puoi elencarli, leggerli e (se il sondaggio è tuo) eliminarli; POST/comments e PUT/comments/{id} rispondono 501.
  • Utenti. Non ci sono profili pubblici: /users/@me (o il tuo id) funziona, qualsiasi altro utente restituisce 404. username è null e user_meta contiene solo valori predefiniti. PATCH/users/@me modifica displayname.
  • Media. POST/upload accetta immagini (JPEG, PNG, GIF o WebP, fino a 5 MB). Video e media di YouTube e Giphy non sono supportati, quindi POST/media e PUT/media/{id} rispondono 501. DELETE/media/{id} rifiuta le immagini ancora mostrate in un sondaggio.
  • I contatori che non esistono più, come view_count e i punti, valgono 0.
  • Gli errori sono oggetti JSON con error e code, e valgono gli stessi limiti di frequenza della v4.

Le tue chiavi esistenti

Le chiavi della piattaforma precedente continuano a funzionare una volta trasferito il tuo account. Puoi anche creare nuove chiavi in Impostazioni → Chiavi API; funzionano sia per la v3 sia per la v4.