非开发者也能看懂的 REST API

什么是 REST API？

当你使用一款应用时，屏幕上显示的许多信息其实来自外部服务。

目的地的天气、包裹状态、商品价格、预订信息或支付结果：应用通常不会直接管理所有这些数据，而是向其他系统请求数据。

这正是 API 发挥作用的地方。 API 允许两个软件系统按照一套明确的规则进行通信。REST API 是在 Web 上实现这种通信最常见的方式之一。 你可以把它理解为应用之间的一场结构化对话：

“把这件商品的信息给我。”

服务响应：

“这是商品名称、价格和库存状态。”

或者：

“为这位客户创建一个新预订。”

服务可能会响应：

“预订已创建。”

REST 是 Representational State Transfer（表述性状态转移） 的缩写。不过，要理解其工作原理，你并不需要记住这个全称。 核心概念其实很简单：REST API 将数据组织成各种资源，例如用户、商品、订单或预订，并定义读取、创建、更新或删除这些资源的标准方式。

一个现实中的例子

假设有一款旅行应用，可以显示你即将前往的目的地天气。 这款应用不一定需要自行收集和更新所有天气数据，而是可以向天气服务的 API 发送请求。

整个流程如下：

你的应用 → API 请求 → 天气服务 → 响应 → 你的应用

响应中可能包含温度、天气状况以及未来几天的预报。 用户看到的只是天气信息，但在这个界面背后，两个系统正在相互通信。

餐厅类比

理解 API 的一种简单方式，是想象自己正在餐厅里用餐。

• 你就是提出需求的应用。
• 菜单说明了你可以点什么。
• 服务员接收请求并带回响应。
• 厨房则是实际完成工作的服务。

API 同时扮演菜单和服务员的角色。它会告诉你可以请求什么、如何提出请求，以及可以期待什么样的响应。 点菜时，你不需要了解厨房内部如何运作。同样，应用在使用某项服务的 API 时，通常也不需要知道该服务内部是如何实现的。

REST API 请求如何工作？

每个 API 请求都包含几项必要信息。

端点：请求要发送到哪里

**端点（endpoint）**是请求发送到的地址。 例如：

https://api.example.com/products/42

它可能代表 ID 为 42 的商品。 不同端点可以代表一组资源、某个单独项目或一项特定操作。

HTTP 方法：你想执行什么操作

HTTP 方法会告诉服务你想执行哪种操作。 最常见的方法包括：

• GET → 获取信息；
• POST → 创建新资源；
• PUT 或 PATCH → 更新现有资源；
• DELETE → 删除资源。

例如，在预订平台中：

GET /bookings

可能用于获取预订，而：

POST /bookings

则可能用于创建新预订。 这些都是广泛采用的惯例，但并非绝对规则。API 文档始终是最权威的参考依据。

请求头和请求体：补充信息

**请求头（headers）**包含请求所需的辅助信息，例如数据格式或用于身份验证的凭据。 **请求体（body）**则包含执行操作所需的数据。 例如，如果你想创建一个预订，请求体可能包含：

{
  "service": "Consultation",
  "date": "2026-09-15",
  "time": "14:00"
}

这些数据通常采用 JSON 格式。JSON 因结构清晰，而且便于人和软件阅读，所以得到了广泛使用。

收到响应后会发生什么？

服务收到请求后会进行处理，并返回一个响应。 响应通常包含所请求的数据或操作结果，以及一个用于说明处理情况的 HTTP 状态码。 最常见的状态码大致分为三类。

200–299：一切正常

请求已成功处理。 例如：

• 200 OK → 请求已完成；
• 201 Created → 新资源已创建。

400–499：请求存在问题

问题通常出在请求本身或客户端权限上。 例如：

• 400 Bad Request → 数据无效；
• 401 Unauthorized → 缺少身份验证信息或验证信息无效；
• 403 Forbidden → 用户不具备所需权限；
• 404 Not Found → 请求的资源不存在。

500–599：服务器端出现问题

负责处理请求的服务遇到了故障。 不过，对普通用户来说，409 或 500 这样的代码并没有太大意义。 因此，一款设计良好的应用应该把技术错误转换成清晰易懂的提示：

“这个预约时段已不可用，请选择其他时间。”

这远比下面这句话更有帮助：

“HTTP 409 Conflict。”

REST API、数据库、Webhook 和 GraphQL 有什么区别？

这些技术和概念彼此相关，但用途不同。

REST API 与数据库

数据库负责存储信息。 而 API 则定义其他系统可以如何与这些信息交互。 例如，数据库可能包含：

• 用户；
• 商品；
• 订单；
• 预订。

API 可以决定哪些数据能够被读取、创建或更新，以及谁有权执行这些操作。 这就在应用和数据之间增加了一层控制。如果没有充分的安全措施，让浏览器直接连接数据库，可能会暴露本应保密的信息或操作。 在 Coderblock 中，你可以通过对话让智能体设计并应用 Postgres 数据库架构。标准 Web 应用会使用专属 Supabase 项目，其中包含 Postgres、Auth、Storage 和 Row Level Security。 你还可以在 Backend 区域查看数据表、已验证用户、存储空间和函数。

REST API 与 Webhook

API 和 Webhook 的信息传递方向不同。 使用标准 API 请求时，由你的应用主动询问信息：

“支付成功了吗？”

使用 Webhook 时，则是另一个服务主动通知你的应用发生了某件事：

“这笔支付刚刚成功完成。”

Webhook 特别适合处理稍后才会发生的事件，例如支付结果、物流更新或订单状态变化。 不过，Webhook 必须经过验证，并以安全的方式处理。 在 Coderblock 托管的 Stripe 流程中，平台可以负责配置 Webhook。在 BYOK 模式下，智能体会安全地请求 Stripe 密钥，并自动配置 Webhook。

REST 与 GraphQL

REST 和 GraphQL 是应用之间进行通信的两种不同方式。 使用 REST 时，通常会通过多个端点处理不同资源。 GraphQL 则提供一个查询接口，让客户端可以明确指定自己希望接收哪些数据。 当数据需求较为复杂，而且客户端需要更精细地控制响应内容时，GraphQL 会特别有用。 另一方面，REST 应用广泛，而且通常更容易理解。 不过，两者并不存在放之四海而皆准的优劣之分。正确的选择取决于服务架构、产品需求、团队情况，以及使用该服务的客户端类型。

身份验证与授权不是一回事

有两个概念经常被混淆：身份验证（authentication）和授权（authorization）。 它们的区别很简单。 身份验证：

“你是谁？”

授权：

“你可以做什么？”

假设一个平台同时拥有客户和管理员。 登录操作用于确认你确实是某个特定用户，但这并不意味着你自动获得查看应用内全部数据的权限。 客户可能只能查看自己的预订。 管理员则可能可以查看所有客户的预订。 两者使用的是同一类身份信息，但拥有不同的权限。

API 密钥又是什么？

API 密钥通常用于识别发出请求的应用或服务。 而经过身份验证的会话，则可以识别已经登录的用户。 两者都不应该被视为万能通行证。

权限必须单独定义，并在服务器端或数据库端强制执行。 在 Coderblock 中，你可以直接在聊天中提出要求：

“添加登录和用户账户功能。”

智能体可以配置 Supabase Auth、注册和登录页面、会话管理、受保护的路由，以及与已验证用户关联的 Row Level Security。 应用还会包含用户资料和角色的基础结构。 这意味着你不需要手动创建密码表，也不必从零开始实现身份验证逻辑。

API 密钥应该存放在哪里？

私密凭据是另一个必须认真考虑的问题。 秘密 API 密钥不应该放在前端、发布到 GitHub，也不应该存入用户可以访问的字段。 当 Coderblock 项目需要某项秘密信息时，智能体可以通过安全请求收集环境变量。 该值会保存在项目的服务器端秘密存储中，不会被添加到前端代码或对话里。

如何设计使用 API 的功能

使用 AI 构建工具开发应用时，不需要先从技术入手。 首先考虑你希望为用户带来的结果。 “向客户显示订单配送状态”就比下面这样的要求更有用：

“添加一个 API。”

然后，你可以进一步明确具体需求。

1. 确定数据来源

哪个系统保存着正确的信息？ 是你的数据库、外部服务、Stripe，还是物流管理系统？ 必须明确唯一且可靠的事实来源。

2. 查看文档

集成服务之前，请确认：

• 可用的端点；
• 身份验证方式；
• 测试环境；
• 使用限制；
• 请求和响应格式；
• 是否支持 Webhook。

3. 提前规划错误处理

如果外部服务响应缓慢，该怎么办？ 如果服务暂时离线呢？ 如果它返回的数据不完整呢？ 即使 API 没有按预期响应，设计良好的应用也应该有明确的处理方式。

4. 验证传入和传出的数据

不要假设从外部服务收到的所有内容永远都是正确的。 数据在使用或存储之前必须经过验证。

5. 限制权限

集成服务应该只获得实际所需的访问权限。 如果某项服务需要读取支付信息，并不意味着它也应该能够修改支付信息。

6. 保护秘密信息

私密凭据必须保留在服务器端。 浏览器绝不能接收到可以执行受限操作的 API 密钥。

7. 上线前进行测试

只要条件允许，就应使用服务提供的测试环境。 除了测试成功操作，还要测试请求被拒绝、错误、超时、重复操作和取消等情况。

8. 避免不必要的请求

并非所有信息都需要在每次页面加载时重新请求。 如果数据条件允许，可以使用缓存来缩短响应时间、减少请求数量并降低集成成本。

在 Coderblock 中使用 API

在 Coderblock 中，API 可以融入构建应用其他部分时所采用的同一套对话式工作流程。 你可以从一个想法或产品模板开始，让 AI 创建前端、后端和数据库。

想要添加集成功能时，最好直接描述你希望实现的行为。 例如：

“添加账户访问功能。每位客户只能查看自己的预订。如果外部预约服务不可用，请显示清晰的提示，并允许用户重试。”

这样的请求不仅说明了要使用哪种技术，更重要的是明确了应用应该如何运行。 智能体可以处理底层实现，而你可以在 coderblock.dev 的实时预览中检查结果，并通过聊天继续调整。

即使不会编程，理解 API 为什么仍然有用？

你不需要成为开发者，也能理解 REST API 的基本概念。 但掌握这些基础知识，会改变你设计应用的方式。它能帮助你理解为什么 Stripe 集成不同于连接数据库、Webhook 为什么不同于标准 API 请求，以及为什么 API 密钥绝不能暴露在前端。 更重要的是，它能帮助你为 AI 编写更好的提示词。

与其只说：

“添加一个 API。”

不如说明应该发生什么、使用哪些数据、谁可以访问这些数据，以及出现问题时应该如何处理。 AI 可以承担大量技术上的复杂工作。

不过，你越能清晰地描述自己想要的行为，就越能掌控正在构建的产品。