API の一貫性

X API v2 の全エンドポイントに共通する一貫したパターン

X API v2 は、すべてのエンドポイントで一貫したパターンが保たれるように設計されています。1 つのエンドポイントの動作を理解すれば、同じパターンを他のあらゆる場所にも適用できます。

---

統一パターン

URL 構造

すべての v2 エンドポイントは予測可能なパターンに従います。

/version/resource/{id}?parameters
/version/resource/verb?parameters

例：

/2/tweets/1234567890                    # Get a specific post
/2/tweets/search/recent                 # Search recent posts
/2/users/by/username/xdevelopers        # Get user by username
/2/users/1234/followers                 # ユーザーのフォロワーを取得

レスポンス構造

すべてのレスポンスは、同じトップレベル構造を持ちます。

{
  "data": { ... },       // プライマリオブジェクト
  "includes": { ... },   // 展開されたオブジェクト
  "meta": { ... },       // ページネーション、カウント
  "errors": [ ... ]      // 部分的なエラー(存在する場合)
}

ID の形式

すべての ID は、プログラミング言語間の互換性を確保するため、文字列として返されます。

{
  "id": "1234567890123456789",
  "author_id": "2244994945"
}

---

Fields と expansions

同じ fields と expansions パラメータを一貫して利用できます。

Object	Fields parameter	Works across
Post	tweet.fields	投稿を返すすべてのエンドポイント
User	user.fields	ユーザーを返すすべてのエンドポイント
Media	media.fields	media expansions をサポートするすべてのエンドポイント
Poll	poll.fields	poll expansions をサポートするすべてのエンドポイント
Place	place.fields	place expansions をサポートするすべてのエンドポイント

---

オブジェクトスキーマ

オブジェクトの type が同じであれば、どのエンドポイントから返されても同じフィールドを持ちます。

• search から取得したポストは、lookup から取得したポストと同じフィールドを持ちます
• followers から取得したユーザーは、search から取得したユーザーと同じフィールドを持ちます
• 展開されたオブジェクトは、そのスタンドアロンのオブジェクトと同一です

---

認証

すべてのエンドポイントでは同じ認証方式が使用されます。

方式	ヘッダー形式
ベアラートークン	Authorization: Bearer {token}
OAuth 1.0a	Authorization: OAuth {parameters}
OAuth 2.0	Authorization: Bearer {user_token}

---

エラー処理

errors フィールドは一貫した形式です。

{
  "title": "Invalid Request",
  "detail": "The query parameter is missing",
  "type": "https://api.x.com/2/problems/invalid-request"
}

すべてのエラータイプを見る →

---

ページネーション

すべてのページネーション対応エンドポイントでは同じトークン方式を使用します。

Parameter	説明
max_results	1ページあたりの結果数
pagination_token	next_token または previous_token から取得したトークン

ページネーションの詳細はこちら →

---

命名規則

• 米国英語のスペル (favorites を使い、favourites は使わない)
• フィールド名にはスネークケースを使用 (author_id、created_at)
• 用語は一貫させる (フィールドでは retweet_count を使い、repost_count は使わない)

---

空の値

値を持たないフィールドは、null を返すのではなく、レスポンスから省略されます。

// User without a bio
{
  "id": "1234",
  "name": "Example User",
  "username": "example"
  // "description" は省略されており、null ではない
}

---

エンティティの一貫性

entities オブジェクトには、テキストから解析されたエンティティのみが含まれます:

• urls
• hashtags
• mentions
• cashtags

メディアと投票は entities ではなく attachments に含まれます。

---

これがあなたにとって何を意味するか

一度学べばどこでも使える

あるエンドポイントで学んだパターンは、すべてのエンドポイントに適用できます。

予測しやすいレスポンス

同じオブジェクト type は、API 全体で同じ構造を持ちます。

シンプルなコード

共通パターン向けに再利用可能な関数を作成できます。

デバッグが容易

一貫したエラー形式により、トラブルシューティングがしやすくなります。

---

不一致を報告する

不一致を見つけましたか？以下からお知らせください：

• Developer Forum
• Developer Feedback