メインコンテンツへスキップ

​
X API v2 のエンドポイント間の一貫性

X API の新しい v2 の大きな特徴のひとつは、エンドポイント間の一貫性です。これは、返却されるオブジェクト、機能、そして API の挙動が、類似するエンドポイント間で一様であることを意味します。 すべてのエンドポイントで、次の要素は同一であると考えて差し支えありません。

​
パスの命名

パスの命名には常にエンドポイントのバージョンが含まれ、その後にリソースが続きます。さらに、先行するリソースに関連するID、返すデータを決定するのに役立つ選択動詞（例: search や sample）、データの配信方法を決定するのに役立つ配信動詞（例: stream）、または主要なリソースと関係を持つ他のリソース（例: /user/12/tweets）を含めることができます。最後に、エンドポイントでクエリパラメータを受け付ける場合は、末尾にクエリパラメータを付加できます。 これらのパスおよびクエリアイテムの構成例をいくつか示します: /version/resource/id?param1=value&param2=value /version/resource/delivery/selection?param1=value&param2=value 実際のリクエスト例: /2/tweets/1067094924124872705?expansions=attachments.media_keys&tweet.fields=author_id /2/users/2244994945?user.fields=created_at,description /2/tweets/search/stream /2/tweets/search/recent?query=snow

​
JSON Schema

リクエストへのレスポンスは JSON Schema を使用して定義されています。つまり、リクエストは常にオブジェクトの集合を配列として返し、各要素には id が付与されます。リクエストが、id をキーとするマップ（連想配列）を返すことはありません。

​
レスポンスオブジェクトとパラメータ

返されるデフォルトのオブジェクトは、そのオブジェクトタイプの各エンドポイントで同一です。
  • id は常に文字列です。
  • パラメータおよびレスポンスフィールドは一貫して米国英語の綴りを使用します。
  • 値がない場合、フィールドは空になるか返されません。
  • entities オブジェクトには、Post のテキスト由来のエンティティのみが含まれます。urls、hashtags、mentions、cashtags が該当します。
  • media_keys および poll_ids フィールドを含むカード関連のすべての情報は、attachments オブジェクトで返されます。
以下は、単一の Post ルックアップ エンドポイントのレスポンスオブジェクト例です（tweet.fields パラメータに author_id、entities を指定）: 
{
   "data": {
       "id": "1278747501642657792",
       "text": "Twitter の Developer Labs が開始されてから1年が経ちました。\n\n次世代の #TwitterAPI の構築に向けて(近日公開予定)、私たちがこれまでに学び、変更してきたことをご覧ください。https://t.co/WvjuEWCa6G",
       "author_id": "2244994945",
       "entities": {
           "urls": [
               {
                   "start": 188,
                   "end": 211,
                   "url": "https://t.co/WvjuEWCa6G",
                   "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html",
                   "display_url": "blog.x.com/developer/en_u…",
                   "images": [
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=orig",
                           "width": 1600,
                           "height": 600
                       },
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=150x150",
                           "width": 150,
                           "height": 150
                       }
                   ],
                   "status": 200,
                   "title": "Twitter Developer Labs の1年:学んだことと変更したこと",
                   "description": "Labs は、何がうまく機能し何が機能しないのか、皆様が何を気に入り何を気に入らなかったのかを理解する上で非常に貴重な役割を果たしてきました。",
                   "unwound_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html"
               }
           ],
           "hashtags": [
               {
                   "start": 106,
                   "end": 117,
                   "tag": "TwitterAPI"
               }
           ]
       }
   }
}

​
認証

すべての X API v2 エンドポイントでは認証が必要です。その多くは OAuth 2.0 Bearer Token に対応しており、エンドポイントへのリクエストに Bearer Token を含める必要があります。 他のユーザーに代わってデータの作成・操作・取得を行うための認可が必要なエンドポイントでは、OAuth 1.0a ユーザーコンテキスト を使用します。これは、あなたのアプリのAPI キーとトークンに加え、リクエスト対象のユーザーに代わって生成したユーザーアクセス トークンを提供することを意味します。3-legged OAuth フローを使うとアクセス トークンを取得できます。認可ヘッダーを自動的に組み立てるツールやライブラリを使用してください。 認証の詳細は、認証に関するドキュメントをご参照ください。

​
Fields

各エンドポイントで返されるオブジェクトは簡略化されています。API のレスポンスをより柔軟にカスタマイズできるよう、希望する fields を指定するために fields パラメータを使用します。fields はエンドポイント間で一貫しています。Post オブジェクトは、Post オブジェクトが返されるすべてのエンドポイントで同じ fields を返します。類似のエンドポイント間で同一の fields セットをクエリできます。 たとえば、同じ Post の fields は、Posts lookup と、Users lookup における展開されたピン留め Post でもクエリできます。

​
Expansions

適切な場合、expansionsは、すべてのネストされた id フィールド（例：author_id のような、*_id と名付けられたすべてのフィールド）で利用できます。Expansions は、現在のオブジェクトのトップレベル識別子ではない id を持つすべてのフィールドでも利用可能です。たとえば、Posts lookupでは、Post はフィールド id をトップレベル識別子とする現在のオブジェクトです。author_id や referenced_tweets.id フィールドは、これらの値をカンマ区切りで expansions パラメータに追加することで、完全なユーザーまたは Post オブジェクトに展開できます。 これらのフィールドに関連して気付いた不整合の報告にご協力ください。