一致性

​

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 作为键的映射（map）。

​

响应对象与参数

对于同一对象类型的各个端点，默认返回的对象一致：

• id 始终为字符串。
• 参数和响应字段统一使用美式拼写。
• 若无值，字段为空或不返回。
• entities 对象仅包含来自 Post 文本的实体：包括 urls、hashtags、mentions 和 cashtags。
• 所有与卡片相关的信息（包括 media_keys 和 poll_ids 字段）均在 attachments 对象中返回。

以下是来自单条 Post 查询端点的示例响应对象（将 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 端点都需要进行认证。其中许多端点支持 OAuth 2.0 Bearer Token 方法，请在请求端点时附带 Bearer Token 以成功调用。

对于需要代表其他用户创建、修改或检索数据的端点，请使用 OAuth 1.0a 用户上下文。这意味着需要提供你的 开发者应用 的 API keys and tokens，以及一组为所代表用户生成的用户 Access Tokens。3-legged OAuth flow 可帮助你获取 Access Tokens。请使用可自动构建授权标头的工具或库。

有关认证的更多信息，请参阅我们的认证文档。

---

​

字段

各端点返回的对象是精简的。为便于开发者按需定制 API 响应，可使用 fields 参数请求所需字段。各端点的字段保持一致。凡返回 Post 对象的端点，其返回的 Post 字段一致。相似端点也可查询同一组字段。

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

​

扩展

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

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