一貫性

​

X API v2 の endpoint 間における一貫性

X API の新しい v2 の主な特徴の一つは、endpoint 間での一貫性です。これは、返されるオブジェクト、機能、そして API の挙動が、同種の endpoint で統一されていることを意味します。

すべての endpoint において、以下の要素は同一です。

​

パスの命名

パス名には常に endpoint のバージョンが含まれ、その後にリソースが続きます。さらに、パスには前述のリソースに関連するID、返すデータを絞り込むのに用いる選択動詞（例: search、sample）、データの配信方法を示す配信動詞（例: stream）、または主要なリソースと関係を持つ他のリソース（例: /user/12/tweets）を含められます。最後に、endpoint がクエリパラメータを受け付ける場合は、末尾にクエリパラメータを付加できます。

これらのパスおよびクエリ要素の構成例は次のとおりです:

/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 をキーとするマップを返すことはありません。

​

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

デフォルトで返されるオブジェクトは、そのオブジェクト種別の各endpointで同一です。

• id は常に文字列です。
• パラメータおよびレスポンスのfieldsは一貫して米国英語の綴りを使用します。
• 値がないfieldsは空、もしくは返されません。
• entities オブジェクトには、Post本文に由来するエンティティのみが含まれます。これには urls、hashtags、mentions、cashtags が含まれます。
• media_keys および poll_ids fields を含む、cardsに関連するすべての情報は attachments オブジェクトで返されます。

以下は、single Post lookup endpoint からのレスポンスオブジェクトの例です（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 の endpoint には認証が必要です。多くの endpoint は OAuth 2.0 Bearer Token に対応しており、成功させるにはリクエストに Bearer Token を含める必要があります。

他のユーザーに代わって data を作成・操作・取得するための認可が必要な endpoint には、OAuth 1.0a ユーザーコンテキスト を使用してください。これは、developer App の API Key およびキーおよびトークン に加え、リクエスト対象となるユーザーのために生成した Access Tokens 一式を提供することを意味します。3-legged OAuth フロー を使うと Access Tokens を取得できます。この認可ヘッダーを自動生成する ツールまたはライブラリ を使用してください。

認証の詳細は、authentication のドキュメントをご参照ください。

---

​

フィールド

各 endpoint で返されるオブジェクトは最小限に要約されています。開発者が API から受け取るレスポンスを柔軟にカスタマイズできるよう、必要なフィールドを指定するために fields パラメータを使用します。フィールドは endpoint 間で一貫しています。Post オブジェクトは、Post オブジェクトを返すすべての endpoint で同じフィールドを返します。類似する endpoint 間では同一のフィールドセットをクエリできます。

たとえば、同じ Post のフィールドは、Posts lookup と、Users lookup における展開されたピン留め Post の両方でクエリできます。

---

​

拡張（Expansions）

該当する場合、expansions は、すべてのネストされた id フィールド（例: *_id のようなフィールド名、author_id など）で利用できます。現在のオブジェクトのトップレベル識別子ではない id を持つすべてのフィールドにも拡張が利用可能です。たとえば、Posts ルックアップ では、Post が現在のオブジェクトで、フィールド id がトップレベルの識別子です。author_id や referenced_tweets.id フィールドは、これらのカンマ区切りの値を expansions パラメータに追加することで、完全なユーザーまたは Post オブジェクトとして展開できます。

これらのフィールドに関して気づいた不整合は報告してください。