Zenn
🎉

Dart/Flutterライブラリ「twitter_api_v2」がTwitterの公式サイトに掲載されました

2022/07/13に公開
Flutter
Twitter
Dart
OSS
Twitter API
idea

「twitter_api_v2」がTwitterの公式サイトに掲載されました

twitter_api_v2

以前以下の記事で、Twitter API v2.0をラッピングした、私が開発と保守をしているDart/Flutter向けライブラリのtwitter_api_v2を紹介しました。

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

そして、つい先日Twitterが管理する開発者向けの公式サイトで、twitter_api_v2がDart/Flutterの開発ライブラリとして正式に掲載されました。

https://developer.twitter.com/en/docs/twitter-api/tools-and-libraries/v2#dart

スクリーンショット 2022-07-13 8 18 16

ここまでを振り返ってみてライブラリの開発開始と初期ビルドの公開から約2ヶ月と、開発/テスト/リリースのサイクルをとても足早に進めてきましたが、とても完成度が高いライブラリになりました。

また、Twitter社の方々からも直接フィードバックをもらったことや、公式のTwitter API v2.0の仕様追加や不具合改善に対する提案をする機会もいただけたことが大きな刺激になりました。

ただ、個人の成果物がこうして公式に認められるというのはなんだか不思議な感覚ですね。

さて、報告はこれくらいにして、最新版のtwitter_api_v2について改めて紹介をしたいと思います。

twitter_api_v2とは

twitter_api_v2とは、Twitter API v2.0をラッピングした、Dart/Flutter向けのオープンソースライブラリです。

Dartで作られたCLIアプリやFlutterを使用して作られたアプリケーションに、Twitter API v2.0の仕様を簡単に統合することができます。

現時点（2022/07/10）で、公式から提供されている全てのエンドポイントだけではなく、全てのリクエストフィールドやレスポンスフィールドをサポートしています。また、Twitter API v2.0で特徴的な仕様であるexpansionsやfieldsの仕様も完全にサポートしています。

もともとは英語ドキュメントのみを提供していましたが、有志の方々の貢献によって多くの言語に翻訳されました。日本語ドキュメントも提供していますので、英語が苦手な方でも簡単に使用することができます。

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

https://pub.dev/packages/twitter_api_v2

特徴

✅ 全てのエンドポイントをサポートしています。
✅ 全てのリクエストフィールドとレスポンスフィールドをサポートしています。
✅ リクエストフィールドとレスポンスフィールドには安全で洗練された型を提供しています。
✅ expansionsとfieldsの仕様をサポートしています。
✅ メソッド名を標準化しています。
✅ 高度なStreaming APIをサポートしています。
✅ エンドポイントに対応した各メソッドは詳細にドキュメント化されています。
✅ OAuth 1.0aとOAuth 2.0の認証方式をサポートしています。

サポートしているエンドポイント

先にも書きましたが、現時点（2022/07/10）で、公式から提供されている全てのエンドポイントだけではなく、全てのリクエストフィールドやレスポンスフィールドをサポートしています。また、Twitter API v2.0で特徴的な仕様であるexpansionsやfieldsの仕様も完全にサポートしています。

以下のマトリクスで、Twitter API v2.0が提供しているエンドポイントと。twitter_api_v2が提供してるメソッドとの関係を示しています。

Tweets Service

ツイート

エンドポイント メソッド名
POST /2/tweets createTweet
DELETE /2/tweets/:id destroyTweet

いいね

エンドポイント メソッド名
POST /2/users/:id/likes createLike
DELETE /2/users/:id/likes/:tweet_id destroyLike
GET /2/tweets/:id/liking_users lookupLikingUsers
GET /2/users/:id/liked_tweets lookupLikedTweets

リツイート

エンドポイント メソッド名
POST /2/users/:id/retweets createRetweet
DELETE /2/users/:id/retweets/:source_tweet_id destroyRetweet
GET /2/tweets/:id/retweeted_by lookupRetweetedUsers

引用ツイート

エンドポイント メソッド名
GET /2/tweets/:id/quote_tweets lookupQuoteTweets

ツイート検索

エンドポイント メソッド名
GET /2/tweets/search/all searchAll
GET /2/tweets/search/recent searchRecent

ツイート参照

エンドポイント メソッド名
GET /2/tweets lookupByIds
GET /2/tweets/:id lookupById

ツイート数

エンドポイント メソッド名
GET /2/tweets/counts/all countAll
GET /2/tweets/counts/recent countRecent

ブックマーク

エンドポイント メソッド名
POST /2/users/:id/bookmarks createBookmark
DELETE /2/users/:id/bookmarks/:tweet_id destroyBookmark
GET /2/users/:id/bookmarks lookupBookmarks

タイムライン

エンドポイント メソッド名
GET /2/users/:id/mentions lookupMentions
GET /2/users/:id/tweets lookupTweets
GET /2/users/:id/timelines/reverse_chronological lookupHomeTimeline

リプライ非表示

エンドポイント メソッド名
PUT /2/tweets/:id/hidden createHiddenReply
PUT /2/tweets/:id/hidden destroyHiddenReply

Volume Stream

エンドポイント メソッド名
GET /2/tweets/sample/stream connectVolumeStream

Filtered Stream

エンドポイント メソッド名
POST /2/tweets/search/stream/rules createFilteringRules
POST /2/tweets/search/stream/rules destroyFilteringRules
GET /2/tweets/search/stream/rules lookupFilteringRules
GET /2/tweets/search/stream connectFilteredStream

Users Service

フォロー

エンドポイント メソッド名
POST /2/users/:id/following createFollow
DELETE /2/users/:source_user_id/following/:target_user_id destroyFollow
GET /2/users/:id/followers lookupFollowers
GET /2/users/:id/following lookupFollowings

ユーザー参照

エンドポイント メソッド名
GET /2/users lookupByIds
GET /2/users/:id lookupById
GET /2/users/by lookupByNames
GET /2/users/by/username/:username lookupByName
GET /2/users/me lookupMe

ミュート

エンドポイント メソッド名
POST /2/users/:id/muting createMute
DELETE /2/users/:source_user_id/muting/:target_user_id destroyMute
GET /2/users/:id/muting lookupMutingUsers

ブロック

エンドポイント メソッド名
POST /2/users/:id/blocking createBlock
DELETE /2/users/:source_user_id/blocking/:target_user_id destroyBlock
GET /2/users/:id/blocking lookupBlockingUsers

Spaces Service

スペース検索

エンドポイント メソッド名
GET /2/spaces/search search

スペース参照

エンドポイント メソッド名
GET /2/spaces lookupByIds
GET /2/spaces/:id lookupById
GET /2/spaces/:id/buyers lookupBuyers
GET /2/spaces/:id/tweets lookupTweets
GET /2/spaces/by/creator_ids lookupByCreatorIds

Lists Service

リスト参照

エンドポイント メソッド名
GET /2/lists/:id lookupById
GET /2/users/:id/owned_lists lookupOwnedBy

ピン留め

エンドポイント メソッド名
POST /2/users/:id/pinned_lists createPinnedList
DELETE /2/users/:id/pinned_lists/:list_id destroyPinnedList
GET /2/users/:id/pinned_lists lookupPinnedLists

ツイート参照

エンドポイント メソッド名
GET /2/lists/:id/tweets lookupTweets

リスト管理

エンドポイント メソッド名
POST /2/lists createPublicList
POST /2/lists createPrivateList
DELETE /2/lists/:id destroyList
PUT /2/lists/:id updateListAsPublic
PUT /2/lists/:id updateListAsPrivate

フォロー

エンドポイント メソッド名
POST /2/users/:id/followed_lists createFollow
DELETE /2/users/:id/followed_lists/:list_id destroyFollow
GET /2/lists/:id/followers lookupFollowers
GET /2/users/:id/followed_lists lookupFollowedLists

メンバー

エンドポイント メソッド名
POST /2/lists/:id/members createMember
DELETE /2/lists/:id/members/:user_id destroyMember
GET /2/lists/:id/members lookupMembers
GET /2/users/:id/list_memberships lookupMemberships

Compliance Service

Batch Compliance

エンドポイント メソッド名
POST /2/compliance/jobs createJob
GET /2/compliance/jobs lookupJobs
GET /2/compliance/jobs/:id lookupJob

標準化されたメソッド名

twitter_api_v2は、それぞれのエンドポイントの性質に基づいて次のような標準的なプレフィックスをメソッド名に付与しています。そのため、使用したいエンドポイントに対応したメソッドを探すのがとても簡単です。

プレフィックス 説明
lookup このプレフィックスはツイートやユーザー等の参照を行うエンドポイントに付与されてます。
search このプレフィックスは広範囲な検索を行うエンドポイントに付与されます。
connect このプレフィックスは高性能なストリーミングを行うエンドポイントに付与されます。
count このプレフィックスは特定の項目を数えるエンドポイントに付与されます。
create このプレフィックスはツイートやフォローといった状態を生成するエンドポイントに付与されます。
destroy このプレフィックスはツイートやフォローといった状態を削除するエンドポイントに付与されます。
update このプレフィックスはツイートやフォローといった状態を更新するエンドポイントに付与されます。

expansionsのサポート

twitter_api_v2は、expansionsの仕様をサポートしています。

例えば、レスポンスオブジェクトに特定のデータのIDが含まれていて、そのIDに紐づく詳細なデータも同時に取得したいという場面があるかもしれません。
そういった場合には、expansionsと呼ばれるTwitter API v2.0の仕様が便利で、twitter_api_v2もその仕様をサポートしています。

基本的にexpansionsはGET通信を行うlookupやsearchの処理で使用できます。
いくつかのフィールドはTwitterResponseのincludesフィールドに格納されます。

次のようにexpansionsを使用できます:

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

void main() async {
  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');

  try {
    final tweets = await twitter.tweetsService.searchRecent(
      query: '#ElonMusk',
      // 必要なフィールドを指定してください.
      expansions: [
        v2.TweetExpansion.authorId,
        v2.TweetExpansion.inReplyToUserId,
      ],
    );

    print(tweets);
  } on v2.TwitterException catch (e) {
    print(e);
  }
}

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

fieldsのサポート

Twitter API v2.0はとても面白い仕様を持っており、ユーザーが場合に応じて各エンドポイントからのレスポンスに含まれるデータ量を制御することができます。
これはfieldsと呼ばれており、twitter_api_v2もこの仕様をサポートしています。

基本的にexpansionsはGET通信を行うlookupやsearchの処理で使用できます。
いくつかのフィールドはTwitterResponseのincludesフィールドに格納されます。

次のようにfieldsを使用できます:

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

void main() async {
  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');

  try {
    final tweets = await twitter.tweetsService.searchRecent(
      query: '#ElonMusk',
      maxResults: 20,
      expansions: v2.TweetExpansion.values,
      tweetFields: [
        v2.TweetField.conversationId,
        v2.TweetField.publicMetrics,
      ],
      userFields: [
        v2.UserField.location,
        v2.UserField.publicMetrics,
      ],
    );

    print(tweets);
  } on v2.TwitterException catch (e) {
    print(e);
  }
}

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

最後に

この記事では触れませんでしたが、ストリーミングAPIをFlutterで使用する方法を以前以下の記事で紹介しましたので、もし興味があれば参照してください。

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

また、DartやFlutterでTwitter関連のアプリケーションを作成する際には、ぜひtwitter_api_v2を使用してください。

GitHubで編集を提案

Discussion