在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

gothinkster/realworld

菜单

API 规范

相关源文件

目的与范围

本文档概述了 RealWorld 应用程序的全面 API 规范。它详细介绍了符合标准化“Conduit”API 规范的 RESTful API 端点、身份验证机制、请求/响应格式和可用资源。本规范作为所有后端实现的契约，以及消耗 API 的前端应用程序的参考。

有关 API 测试的信息，请参阅 API 测试。有关支持此 API 的数据库架构的详细信息，请参阅 数据库架构。

概述

RealWorld API 遵循 RESTful 原则，并以 OpenAPI 3.0 格式定义。该 API 提供了用于在社交博客平台中管理用户、文章、评论、个人资料和标签的端点。

来源： api/openapi.yml1-12 api/README.md1-11

身份验证

API 使用 JWT（JSON Web Token）进行身份验证。所有受保护的端点都需要 Authorization 头中的令牌。

令牌必须包含在 Authorization 头中，格式如下：

Authorization: Token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

来源： api/openapi.yml827-836

API资源

API 提供了以下资源的端点：

用户和身份验证

端点方法描述需要认证
/users/loginPOST登录现有用户否
/usersPOST注册新用户否
/userGET获取当前用户是
/userPUT更新当前用户是

来源： api/openapi.yml22-86

配置文件

端点方法描述需要认证
/profiles/{username}GET获取用户个人资料可选
/profiles/{username}/followPOST关注用户是
/profiles/{username}/followDELETE取消关注用户是

来源： api/openapi.yml87-152

文章

端点方法描述需要认证
/articles/feedGET获取关注用户的文章是
/articlesGET获取全局最新文章可选
/articlesPOST创建文章是
/articles/{slug}GET获取一篇文章否
/articles/{slug}PUT更新一篇文章是
/articles/{slug}DELETE删除一篇文章是

来源： api/openapi.yml153-289

注释

端点方法描述需要认证
/articles/{slug}/commentsGET获取文章评论可选
/articles/{slug}/commentsPOST创建评论是
/articles/{slug}/comments/{id}DELETE删除评论是

来源： api/openapi.yml290-364

收藏

端点方法描述需要认证
/articles/{slug}/favoritePOST收藏一篇文章是
/articles/{slug}/favoriteDELETE取消收藏一篇文章是

来源： api/openapi.yml365-409

标签

端点方法描述需要认证
/tagsGET获取所有标签否

来源： api/openapi.yml410-421

资源关系

下图说明了 API 中关键实体之间的关系

来源： apps/api/prisma/migrations/20241009081140_init/migration.sql1-96 api/openapi.yml423-592

API 端点详解

身份验证端点

登录端点

  • URL: /users/login
  • Method: POST
  • 请求体:
  • 成功响应 (200 OK)

注册端点

  • URL: /users
  • Method: POST
  • 请求体:
  • 成功响应 (201 Created)

来源： api/openapi.yml22-52 apps/documentation/src/content/docs/specifications/backend/api-response-format.md9-21

用户端点

获取当前用户

  • URL: /user
  • Method: GET
  • 需要认证: 是
  • 成功响应 (200 OK)

更新当前用户

  • URL: /user
  • Method: PUT
  • 需要认证: 是
  • 请求体（至少需要一个字段）
  • 成功响应 (200 OK)

来源： api/openapi.yml53-86 apps/documentation/src/content/docs/specifications/backend/api-response-format.md9-21

个人资料端点

获取个人资料

  • URL: /profiles/{username}
  • Method: GET
  • 需要认证: 可选
  • URL 参数: username - 要获取其个人资料的用户名
  • 成功响应 (200 OK)

来源： api/openapi.yml87-107 apps/documentation/src/content/docs/specifications/backend/api-response-format.md23-34

文章端点

获取最近的文章

  • URL: /articles
  • Method: GET
  • 需要认证: 可选
  • 查询参数:
    • tag - 按标签过滤
    • author - 按作者（用户名）过滤
    • favorited - 按用户收藏的文章（用户名）过滤
    • limit - 返回的文章数量限制（默认为 20）
    • offset - 跳过的文章数量（默认为 0）
  • 成功响应 (200 OK)

注意：截至 2024 年 8 月 16 日，出于性能原因，文章列表端点不再返回 body 字段。

来源： api/openapi.yml174-205 apps/documentation/src/content/docs/specifications/backend/api-response-format.md60-103

评论端点

获取文章评论

  • URL: /articles/{slug}/comments
  • Method: GET
  • 需要认证: 可选
  • URL 参数: slug - 要获取评论的文章的 slug
  • 成功响应 (200 OK)

来源： api/openapi.yml290-310 apps/documentation/src/content/docs/specifications/backend/api-response-format.md125-142

标签端点

获取标签

  • URL: /tags
  • Method: GET
  • 需要认证: 否
  • 成功响应 (200 OK)

来源： api/openapi.yml410-421 apps/documentation/src/content/docs/specifications/backend/api-response-format.md144-152

错误处理

API 使用传统的 HTTP 响应代码来指示 API 请求的成功或失败

  • 2xx - 成功
  • 4xx - 错误 (客户端错误)
  • 5xx - 错误 (服务器端错误)

对于错误，API 会返回一致的错误响应格式

来源： api/openapi.yml589-602 api/openapi.yml729-734

API Base URL

API 托管在以下基础 URL

https://api.realworld.io/api

来源： api/openapi.yml19-20

测试 API

有关测试 API 实现的信息，请参阅 API 测试。

API 版本控制

当前 API 版本为 1.0.0。API 不在 URL 中使用显式版本控制，但所有 API 更改都已在 OpenAPI 规范中记录和维护。

来源： api/openapi.yml3-11

API 架构定义

API 架构包含以下主要数据模型

  1. User - 代表系统中的用户及其身份验证详细信息
  2. Profile - 用户的公开表示
  3. Article - 带有标题、内容和元数据的博客文章
  4. Comment - 对文章的评论
  5. Tag - 文章的类别标签

这些模型及其关系在 OpenAPI 规范中定义，并在数据库架构中实现。

来源： api/openapi.yml423-588 apps/api/prisma/migrations/20241009081140_init/migration.sql1-96