開発者向け / 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)で変更なく提供され、同じX-API-Keyヘッダーを受け付け、 v3のOpenAPI仕様のとおり同じJSONでやり取りします。

新しいプロジェクトではForms API(v4)をお使いください。すべての質問タイプ、下書き、回答、招待に対応しています。 v3は今後も不具合の修正は行いますが、新機能は追加されません。

v3の投票は現在どうなっているか

v3の投票はすべて、質問が1つのフォームになっています:

v3のtypeフォームのセクション
textの選択肢を持つmultiple_choicemultiple_choice
imageの選択肢を持つmultiple_choicepicture_choice
ranked_choiceranked_choice
dateとtime_rangeの選択肢を持つmeetingmeeting

投票のidはフォームのslug、選択肢のIDはchoiceのIDなので、2つの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のどちらでも使えます。