面向非开发者的 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 文档为准。

Header 和 body：附加信息

**Header（请求头）**包含辅助请求的信息，例如数据格式或用于身份验证的凭据。 **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 应用范围非常广，而且通常更容易理解。 但不存在一种对所有情况都最好的方案。具体选择取决于服务架构、产品需求、团队以及使用它的客户端类型。

身份验证与授权：两者并不相同

两个经常被混淆的概念是身份验证和授权。 它们之间的区别很简单。 身份验证：

“你是谁？”

授权：

“你可以做什么？”

假设一个平台同时包含客户和管理员。 登录用于确认你确实是某个特定用户，但这并不意味着你可以自动查看应用中的所有数据。 客户可能只能查看自己的预约。 管理员则可能查看所有客户的预约。 基础身份信息可以相同，但权限并不一样。

API key 又是什么？

API key 通常用于识别正在发起请求的应用或服务。 而经过身份验证的会话可以识别已经登录的用户。 这两者都不应被视为能够访问一切的万能通行证。

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

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

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

API key 应该放在哪里？

私密凭据是另一个至关重要的问题。 私密 API key 不应写入前端、发布到 GitHub，或保存在用户能够访问的字段中。 当 Coderblock 项目需要某项密钥时，智能体可以通过安全请求获取密钥，并将其作为环境变量保存。 该值会存储在项目服务器端的密钥存储中，不会被写入前端代码或聊天记录。

如何设计使用 API 的功能

使用 AI builder 构建应用时，不必从技术选型开始。 应该先明确你希望为用户实现什么结果。 “让客户查看自己订单的配送状态”比下面这种要求更有用：

“添加一个 API。”

在此基础上，你可以进一步确定所需内容。

1. 确定数据来源

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

2. 查看文档

集成服务之前，请检查：

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

3. 考虑错误情况

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

4. 验证输入和输出数据

不要默认外部服务返回的内容始终正确。 数据在使用或保存之前必须经过验证。

5. 限制权限

一项集成应该只获得完成工作真正需要的权限。 如果某项服务只需读取支付信息，就不一定还要拥有修改支付信息的权限。

6. 保护密钥

私密凭据必须保留在服务器端。 浏览器不应接收到能够执行敏感操作的 API key。

7. 上线前测试

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

8. 避免不必要的调用

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

在 Coderblock 中使用 API

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

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

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

这样的要求不仅说明了要使用什么技术，更重要的是明确了应用中应该发生什么。 智能体可以处理底层实现，而你可以在 coderblock.dev 的实时预览中检查结果，并继续通过聊天进行完善。

即使不会编程，了解 API 也很有用

你不必成为开发者，也能理解 REST API 的基本概念。 但掌握这些基础知识，会改变你设计应用的方式。你会明白为什么 Stripe 集成不同于连接数据库，为什么 Webhook 不同于普通 API 请求，以及为什么绝不能在前端暴露 API key。 更重要的是，它能帮助你向 AI 提出更准确的要求。

与其只说：

“添加一个 API。”

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

但你越能清楚地描述希望实现的行为，就越能掌控自己正在构建的产品。