一致性

​

X API v2 各个 endpoint 之间的一致性

X API 新的 v2 版本的一个主要特点是各个 endpoint 之间的一致性。这意味着在相似的 endpoint 上，API 返回的对象、功能和行为是统一的。

你可以预期以下元素在所有 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 始终为字符串。
• 参数和响应字段统一使用美式英语拼写。
• 若无值，字段将为空或不返回。
• entities 对象仅包含源自 Post 文本的实体：包括 urls、hashtags、mentions 和 cashtags。
• 所有与卡片相关的信息（包括 media_keys 和 poll_ids 字段）均在 attachments 对象中返回。

下面是来自单个 Post 查找 endpoint 的示例响应对象（tweet.fields 参数设置为 author_id、entities）：

{
   "data": {
       "id": "1278747501642657792",
       "text": "自 Twitter 开发者实验室推出以来已经过去了一年。\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 开发者实验室一周年：我们的收获与改进",
                   "description": "实验室在帮助我们了解什么有效、什么无效，以及您的喜好和不满方面发挥了宝贵作用。",
                   "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 都需要身份验证。其中许多支持 OAuth 2.0 Bearer Token 方法，需要在对该 endpoint 的请求中附带 Bearer Token 才能成功调用。

对于需要在代表其他用户的情况下创建、操作或检索数据的 endpoint，请使用 OAuth 1.0a 用户上下文。这意味着需要提供你的开发者 App的API Key 和令牌，以及一组为被代表的用户生成的用户 Access Tokens。三方 OAuth 授权流程可帮助你获取 Access Tokens。请使用可自动构建该授权标头的工具或库。

关于身份验证的更多信息，请参阅我们的身份验证文档。

---

​

字段

每个 endpoint 返回的对象都是精简的。为便于开发者定制 API 响应，可使用 fields 参数请求所需字段。各个 endpoint 的字段保持一致。Post 对象在所有返回该对象的 endpoint 上都会返回相同的字段。相似的 endpoint 也可以查询同一组字段。

例如，相同的 Post 字段既可在 Posts lookup 中查询，也可用于 Users lookup 中展开的置顶 Post。

---

​

扩展（Expansions）

在适当情况下，expansions 适用于所有嵌套的 id 字段（例如所有命名为 *_id 的字段，如 author_id）。对于所有包含 id 且该 id 并非当前对象顶级标识符的字段，也提供扩展。举例来说，在 Posts 查找 中，当前对象为 Post，其 id 字段为顶级标识符。通过将这些以逗号分隔的值添加到 expansions 参数中，可将 author_id 或 referenced_tweets.id 字段扩展为完整的用户或 Post 对象。

如您发现与这些字段相关的任何不一致之处，请提交反馈。