Desenvolvedores / Referência da API

Poll API

v3

As integrações criadas para a API anterior do StrawPoll continuam funcionando. Veja como a v3 corresponde aos formulários.

URL base
https://api.strawpoll.com/v3
Especificação
OpenAPI 3

A Poll API v3 continua funcionando

O código escrito para a API anterior do StrawPoll continua funcionando. Os endpoints v3 continuam sendo servidos da mesma forma em https://api.strawpoll.com/v3 (e https://strawpoll.com/api/v3), aceitam o mesmo cabeçalho X-API-Key e falam o mesmo JSON, como descrito na especificação OpenAPI v3.

Para projetos novos, use a Forms API (v4): ela cobre todos os tipos de pergunta, além de rascunhos, respostas e convites. A v3 continuará recebendo correções, mas não recursos novos.

No que uma enquete v3 se transformou

Cada enquete v3 é um formulário de uma única pergunta:

type v3Seção do formulário
multiple_choice com opções textmultiple_choice
multiple_choice com opções imagepicture_choice
ranked_choiceranked_choice
meeting com opções date e time_rangemeeting

O id de uma enquete é o slug do formulário, e os identificadores de opções são identificadores de choices. Assim, você pode combinar as duas APIs: criar uma enquete com a v3 e ler as respostas com a v4, ou o contrário. require_voter_names adiciona uma seção de dados de contato que pede um nome.

Formulários com várias perguntas podem ser lidos pela v3, que mostra a primeira pergunta. Qualquer alteração pela v3 é recusada com 409 unsupported_form: assim a v3 nunca exclui perguntas que não vê. Use a v4 para esses formulários.

Configurações

poll_configConfiguração do formulário
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, com comentários públicos
allow_vpn_userso contrário de blockVPNUsers
force_appearance: light, dark, autoo tema claro ou escuro do StrawPoll, ou nenhum
is_multiple_choice, multiple_choice_min, multiple_choice_maxiguais, e 0 significa sem limite
allow_other_optionrespostas livres
randomize_optionsopções embaralhadas
allow_indeterminaterespostas “se necessário” nas enquetes de reunião
require_voter_namesuma pergunta de nome; sempre ativa nas enquetes de reunião

PUT/polls/{id} mantém cada configuração que você omitir em poll_config, assim como os votos das opções cujo id você enviar de novo.

Formulários configurados no editor podem usar verificações que a v3 não conhece. Elas aparecem com o valor v3 mais próximo: uma verificação por nome como session, uma verificação por e-mail como invite.

As diferenças que vale a pena conhecer

  • As enquetes são publicadas na hora. A v3 não tinha rascunhos. As alterações com PUT ficam no ar imediatamente; um rascunho aberto no editor não é afetado.
  • is_private sempre vale true. Na nova plataforma, as enquetes nunca aparecem publicamente em listagens.
  • Resultados. poll_votes vale 1 (escolhida ou sim), 0 (não escolhida ou não), 2 (se necessário) e null (sem resposta). Em ranked_choice, é a posição que o participante deu à opção, sendo 1 a primeira. poll_participants fica vazio, a menos que os nomes sejam públicos ou a enquete seja sua. Resultados que você ainda não pode ver respondem 403 results_hidden.
  • As respostas livres aparecem como opções adicionais com is_write_in: true.
  • Os comentários são notas que os participantes deixam junto com o voto. Você pode listá-los, lê-los e (como dono da enquete) excluí-los; POST/comments e PUT/comments/{id} respondem 501.
  • Usuários. Não há perfis públicos: /users/@me (ou o seu próprio id) funciona, e qualquer outro usuário retorna 404. username vale null e user_meta contém apenas valores padrão. PATCH/users/@me altera displayname.
  • Mídia. POST/upload aceita imagens (JPEG, PNG, GIF ou WebP, até 5 MB). Vídeos e mídias do YouTube e do Giphy não são compatíveis: por isso POST/media e PUT/media/{id} respondem 501. DELETE/media/{id} recusa imagens que uma enquete ainda exibe.
  • Os contadores que não existem mais, como view_count e os pontos, valem 0.
  • Os erros são objetos JSON com error e code, e valem os mesmos limites de taxa da v4.

Suas chaves atuais

As chaves da plataforma anterior continuam funcionando depois que sua conta for migrada. Você também pode criar chaves novas em Configurações → Chaves de API; elas funcionam tanto para a v3 quanto para a v4.