개발자 / API 레퍼런스

Poll API

v3

이전 StrawPoll API용으로 만든 연동은 계속 작동합니다. v3가 폼에 어떻게 대응하는지 확인하세요.

기본 URL
https://api.strawpoll.com/v3
명세
OpenAPI 3

Poll API v3는 계속 동작합니다

이전 StrawPoll API용으로 작성한 코드는 그대로 실행됩니다. v3 엔드포인트는 https://api.strawpoll.com/v3(및 https://strawpoll.com/api/v3)에서 변경 없이 제공되며, v3 OpenAPI 명세에 설명된 대로 같은 X-API-Key 헤더와 같은 JSON을 사용합니다.

새 프로젝트에는 Forms API(v4)를 사용하세요. 모든 질문 유형과 초안, 응답, 초대를 지원합니다. v3는 버그 수정만 받고, 새 기능은 추가되지 않습니다.

v3 투표는 이제 이렇게 바뀌었습니다

모든 v3 투표는 질문이 하나인 폼입니다.

v3 type폼 섹션
text 선택지가 있는 multiple_choicemultiple_choice
image 선택지가 있는 multiple_choicepicture_choice
ranked_choiceranked_choice
date 및 time_range 선택지가 있는 meetingmeeting

투표 id는 폼의 slug이고 선택지 id는 choice id이므로 두 API를 섞어 쓸 수 있습니다. v3로 투표를 만들고 v4로 응답을 읽거나, 그 반대로도 가능합니다. require_voter_names는 이름을 묻는 연락처 섹션을 추가합니다.

질문이 두 개 이상인 폼도 v3로 읽을 수 있으며, 이때는 첫 번째 질문만 보입니다. 이런 폼을 v3로 변경하면 409 unsupported_form으로 거부되므로, v3가 보이지 않는 질문을 삭제하는 일은 없습니다. 이런 폼에는 v4를 사용하세요.

설정

poll_config폼 설정
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, 공개 댓글
allow_vpn_usersblockVPNUsers의 반대
force_appearance: light, dark, autoStrawPoll 라이트 또는 다크 테마, 또는 테마 없음
is_multiple_choice, multiple_choice_min, multiple_choice_max동일하며, 0은 제한 없음을 뜻합니다
allow_other_option직접 입력 답변
randomize_options선택지 순서 섞기
allow_indeterminate일정 조율 투표의 ‘필요하면 가능’ 답변
require_voter_names이름 질문. 일정 조율 투표에서는 항상 켜져 있습니다

PUT/polls/{id}는 poll_config에서 생략한 설정을 모두 유지하며, id를 다시 보낸 선택지의 표도 유지합니다.

에디터에서 설정한 폼은 v3에 해당 값이 없는 검사를 사용할 수 있습니다. 이런 검사는 가장 가까운 v3 값으로 읽힙니다. 이름 검사는 session, 이메일 검사는 invite로 표시됩니다.

알아 두어야 할 차이점

  • 투표는 즉시 게시됩니다. v3에는 초안이 없었습니다. PUT으로 변경한 내용은 바로 반영되며, 에디터에 열려 있는 초안은 영향을 받지 않습니다.
  • is_private는 항상 true입니다. 새 플랫폼에서는 투표가 공개 목록에 표시되지 않습니다.
  • 결과. poll_votes는 1(선택함 또는 예), 0(선택 안 함 또는 아니요), 2(필요하면 가능), null(응답 없음)입니다. ranked_choice에서는 투표자가 해당 선택지에 매긴 순위이며, 1이 1순위입니다. poll_participants는 이름이 공개되어 있거나 본인 소유 투표가 아니면 비어 있습니다. 아직 볼 수 없는 결과는 403 results_hidden을 반환합니다.
  • 직접 입력 답변은 is_write_in: true가 붙은 추가 선택지로 나타납니다.
  • 댓글은 투표자가 표와 함께 남기는 메모입니다. 목록 조회와 읽기가 가능하며, 투표 소유자는 삭제할 수 있습니다. POST/comments와 PUT/comments/{id}는 501을 반환합니다.
  • 사용자. 공개 프로필은 없습니다. /users/@me(또는 본인 id)는 동작하지만, 다른 사용자는 404입니다. username은 null이고 user_meta에는 기본값만 들어 있습니다. PATCH/users/@me로는 displayname을 변경합니다.
  • 미디어. POST/upload는 이미지(JPEG, PNG, GIF, WebP, 최대 5 MB)를 받습니다. 동영상, YouTube, Giphy 미디어는 지원하지 않으므로 POST/media와 PUT/media/{id}는 501을 반환합니다. DELETE/media/{id}는 투표에서 아직 표시 중인 이미지를 거부합니다.
  • 더 이상 존재하지 않는 카운터(view_count, 포인트 등)는 0입니다.
  • 오류는 error와 code가 있는 JSON 객체이며, v4와 같은 속도 제한이 적용됩니다.

기존 키

이전 플랫폼의 키는 계정이 이전된 뒤에도 계속 동작합니다. 설정 → API 키에서 새 키를 만들 수도 있으며, 새 키는 v3와 v4 모두에서 동작합니다.