Zenn
🤔

個人が公式Twitter APIの機能追加を提案する方法

2022/07/31に公開
Twitter
Twitter API
#
Open Evolution
idea

概要

まずTwitter APIとは、Twitter社が提供している、Twitterが提供しているの様々なサービスをプログラム的に操作することを可能にするAPIです。特定のプログラムから任意のツイートを送信することや、検索したツイートから様々な分析を行うことができます。

https://developer.twitter.com/en/docs/twitter-api

そんなTwitter APIですが、Twitter社の関係者以外でも機能追加の提案を行うことができることをご存知でしょうか。Twitter社はTwitterをより便利かつ強力なプラットフォームにするために、Open Evolutionという社外からアイデアを募るプロジェクトをGitHubで公開しています。

https://github.com/twitterdev/open-evolution

このOpen Evolutionプロジェクトを通して、Twitter社の関係者以外の方でも、Twitter APIをより強力にする創造的なアイデアを自由に提案することが可能です。

ただ、無造作に提案をしていいわけではなく、Twitter社が定めたテンプレートに従う必要があるので、Open Evolutionにあるドキュメントの翻訳も兼ねて提案方法を紹介します。

提案までの流れ

アイデアを提案するまでのワークフローは、READMEの以下のセクションで提示されています。

https://github.com/twitterdev/open-evolution#workflow

上記の内容を翻訳すると以下のようになります。

  1. リポジトリをフォークしてください。
  2. proposal-template.mdをコピーし、タイトルが提案内容を表すように名前を変更します（提案書のタイトルと同じ名前で構いません）。
  3. 提案書のテンプレートに記載されている手順に従って、必要事項を記入してください。
  4. 記入が完了したらプルリクエストを作成してください。レビュー担当者が可能な限り早く提案書の作成者とコンタクトをとり、提案についてディスカッションをします。
  5. レビューがスケジュールされたら、レビュー担当者とあなたの提案について話し合う準備をしてください。審査は15営業日以内に行われる予定です。
  6. レビューの結果として、承認または却下の判断が決定されます。また、レビュー担当者は、修正案の提出を求めることができます。この場合、提案は差し戻され、再度審査の日程が組まれます。

このように、提案書を作成してレビューをしてもらうまでとてもシンプルなワークフローになっています。ただし、提案書は英語で記述する必要がある点に注意してください。

また、提案書を作成してレビュー担当者とディスカッションをするとは言っても、GitHubで文面でのディスカッションになるので、英語に自信のない方であっても翻訳アプリ等を使用することで対応は可能かと思います。

注意事項

  • 提案が受理された場合、Twitterが変更提案に原則的に同意したことを意味します。これは、その提案がすぐに実行されることを意味するものではありません。
  • すべての決定は最終的なものであり、異議を申し立てることはできませんが、却下された提案は、Twitter APIプラットフォームの一般原則を尊重する限り、修正して再投稿することが可能です。
  • 過去に採択・不採択となった提案と重複していないかどうかは、提案書の作者の責任において確認してください。
  • 旧バージョン（v1.1等）のAPIは引き続きサポートされますが、旧バージョンへの変更提案は却下されます（ただし、過去に採用・却下された提案と重複しない限り、現行バージョンに対して再提案することができます）。
  • 提案書の投稿は、Twitter APIプラットフォームの一般原則を遵守している必要があります。これらの要件を満たさない投稿は、レビューなしで却下される場合があります。この場合、コアチームメンバー（リジェクト候補のフラグを立てたメンバーの場合もあります）がレビュー担当者として指名され、リジェクトを実行するか、提案書の作者に修正版の提出を求めます。
  • 提案書の審査は、提案が審議から外された場合や、審査期間内に決定できる場合は、早期に終了することができます。

提案書の作成

提案をするまでの一通りの流れや注意事項がわかったので、提案書を作成する方法と例を紹介します。

テンプレートとして提供されているproposal-template.mdを使用していきます。

Proposal title

まず、「Proposal title」は提案書の名前です。提案する内容を表すわかりやすく簡潔な名前をつけてください。

タイトル

例えば、「ツイート検索をする際に国コードを指定できるオプションを追加すべき」であれば、「Should add an option to specify country code when searching for tweets」になります。

また、提案書のタイトルを考える際には、「強制」をイメージさせる「Must」のような単語ではなく、「提案」や「推奨」をイメージさせる「Should」を使用してください。このような単語のニュアンスを考慮するだけでも、提案書を受け取った担当者の印象が大きく変わります。

Metadata

タイトルの記入が終わったら、次はメタデータの記入をしましょう。具体的には以下の項目です。

メタデータ

上から順に次のように記載してください。

  • Proposal: (link to GitHub PR related to this proposal)
    • この提案書に関連したプルリクエストが既に投稿されている場合には、そのリンクを記入します。
    • もし該当のプルリクエストが存在しなければ無記入で大丈夫です。
  • Discussion: (link to GitHub issue related to this proposal)
    • この提案について事前にIssueである程度話をしていた場合には、そのIssueへのリンクを記入してください。
    • もし該当のIssueが存在しなければ無記入で大丈夫です。
  • Authors:
    • この提案書の作成者名を記入してください。
    • 本名である必要はないですが、レビュー担当者がコンタクトをとる可能性があるので、GitHubやTwitterといったSNSへの有効なリンクを記載してください。
  • Review Manager: TBD (this will be filled by the review manager)
    • レビュー担当者を記入する項目ですが、あらかじめ記入されている未確定を表す「TBD」のままで大丈夫です。
  • Status: Open
    • あらかじめ記入されている「Open」のままで大丈夫です。
    • ステータスの意味はREADMEのStatusesセクションで確認できます。

例えば、次のように記入してください。

-   Proposal: (link to GitHub PR related to this proposal)
    - [#17](https://github.com/twitterdev/open-evolution/pull/17)
-   Discussion: (link to GitHub issue related to this proposal)
    - [#16](https://github.com/twitterdev/open-evolution/issues/16)
-   Authors:
    - KATO, Shinya ([GitHub](https://github.com/myConsciousness), [Twitter](https://twitter.com/_kato_shinya))
-   Review Manager: TBD (this will be filled by the review manager)
-   Status: Open

Introduction

メタデータの記入が完了したら、次は提案書の導入を記入していきましょう。

導入

この導入セクションには、提案するアイデアの概要を記入してください。この導入ではまだ提案の具体的な内容に触れる必要はなく、「なにを実現する機能なのか」を簡潔に表現してください。

Motivation

導入の記入が完了したら、提案をするに至った動機を記入していきましょう。

動機

このセクションでは、あなたがこの提案をするに至った理由と、この提案を採用することによるメリットを記入してください。

このセクションに記入すべきポイントは次のとおりです。

  • 「なぜ」この機能が必要なのか
    • APIが提供している機能に不足がある、または現在の仕様では機能しない
    • APIが提供している機能とユーザーの要求との間で乖離がある
    • 社会情勢の変化によるもの
    • 等々
  • この機能を追加することで得られる「利益」は何なのか
    • この機能を追加することで、APIを使用して作成できるアプリの分野が広がる
    • この機能を追加することで、より高度なツイート分析が可能になる
    • 等々

Proposed solution

動機の記入が完了したら、次は動機セクションで提起した問題の具体的な解決策を記入していきましょう。

解決策

このセクションでは、先の動機セクションで提起した問題を解決するための方法を記入してください。このセクションではまだTwitter APIの設計に関する具体的な改善案を記入する必要はありません。

また、このセクションでは次の項目がポイントになります。ただし、提案をする際に次の項目全てが対象になるわけではなく、提案する内容に合わせてこれらのポイントと合致するかどうかを判断してください。

  • この解決策は開発者目線に立っているか
  • この解決策はAPIを使用する開発者の利便性を改善するか
  • この解決策は従来の解決策（仕様）よりも明確か
  • この解決策は、データ保護の観点から、従来の仕様よりも安全か
  • この解決策は、データの送受信の観点から、従来の仕様よりも効率的か

Detailed design

解決策の記入が完了したら、次は先に挙げた解決策のより具体的なAPIの設計を記入していきましょう。

設計

API設計を記入する際のフォーマットは特に指定がないですが、言語やプラットフォームに依存しない書き方が好ましいでしょう。

例えば、次のようにリクエスト方法とレスポンスデータを記入します。

リクエスト例:

GET https://api.twitter.com/2/users/:id/tweets?tweet.fields=promoted

レスポンス例:

{
   "data": [
     {
       "id": "1338971066773905408",
       "text": "💡 Using Twitter data for academic research? Join our next livestream this Friday @ 9am PT on https://t.co/GrtBOXh5Y1!n n@SuhemParack will show how to get started with recent search & filtered stream endpoints on the #TwitterAPI v2, the new Tweet payload, annotations, & more. https://t.co/IraD2Z7wEg",
       "promoted": true
     },
     {
       "id": "1338923691497959425",
       "text": "📈 Live now with @jessicagarson and @i_am_daniele! https://t.co/Y1AFzsTTxb",
       "promoted": false
     }
   ],
   "meta": {
     "oldest_id": "1338923691497959425",
     "newest_id": "1338971066773905408",
     "result_count": 2,
   }
 }

Compatibility, breaking changes and migrations

具体的なAPI設計を記入し終えたら、次はこの提案した機能が従来の仕様と互換性があるのかを記入します。

互換性

もしこの提案による破壊的変更やマイグレーションが発生しない場合は、無記入または互換性があることを記入してください。

Alternatives considered

最後のセクションでは代替案を記入します。

代替案

代替案がない場合は無記入でも大丈夫ですが、Twitter社の開発チームがこの提案を無視した場合に起こりうるであろう問題を記入しておくとより効果的でしょう。

提案書の提出

ここまでで提案書の記入方法を紹介しました。最後に、作成した提案書のファイルに適切な名前を付けてからプルリクエストを作成しましょう。

作成した提案書のファイル名は次のようなフォーマットにする必要があります。

  • 000-your-proposal-name.md

上記のフォーマットのプレフィックスとしては、Open Evolutionリポジトリのapprovedフォルダにある連番に従って採番してください。

例えば、approvedにある最新のファイルのプレフィックスが「002」である場合は、あなたの提案書のプレフィックスは「003」になるでしょう。ただし、中には他の方のレビューが進行中で近日中にマージされるような提案書もあります。そういった場合には、プルリクエストにある提案書の連番も確認してから採番するといいでしょう。

次に、連番に続く「your-proposal-name」に関しては、提案書に記入したタイトルをハイフン区切りにしたもので構いません。

あとは、プルリクエストを作成してTwitter社のレビュー担当者が反応するのを待つだけです。

Twitter APIをより強力にするために、どんどん提案していきましょう！

宣伝

私はDart言語とFlutterフレームワークにTwitter API v2.0を簡単に統合できるライブラリ「twitter_api_v2」を開発しています。

twitter_api_v2はオープンソースですのでどのような方でも開発に貢献することができます。開発リポジトリの公用語は英語にしていますが、日本人の方々も大歓迎ですのでお気軽にIssueやPull Requestを作成してください。

また、このライブラリが役に立った場合にGitHub の開発リポジトリにスターを付けることや、Pub.dev でいいねを付けることもよろしくお願いします。これはtwitter_api_v2の開発コミュニティを活性化するためにとても大きな意味があります。

もしなにか疑問がある場合は開発リポジトリのディスカッションにでもスレッドを立てていただければと思います。

https://github.com/twitter-dart/twitter-api-v2

https://pub.dev/packages/twitter_api_v2

また、以下の記事も参考にしてください。

https://zenn.dev/kato_shinya/articles/released-twitter-api-v2-dart

https://zenn.dev/kato_shinya/articles/twitter-api-v2-is-listed-in-twitter-official

https://zenn.dev/kato_shinya/articles/how-to-use-twitter-volume-stream-in-flutter

https://zenn.dev/kato_shinya/articles/how-to-use-twitter-filtered-stream-in-flutter

スポンサーの募集

オープンソース開発をサポートしてくださるスポンサーを募集しています。少額($1)からの寄付も可能ですので、以下のリンクから是非ご支援ください。

https://github.com/sponsors/myconsciousness

また、この記事にバッジを贈っていただくことでも支援は可能です。

GitHubで編集を提案

Discussion