PricingLoginStart free
AI SaaS Builder · 课时

设计 RESTful API

创建结构清晰且高效的 API，实现前端与后端之间的顺畅通信。

第 1 / 4 课12 个步骤

设计 RESTful API 是 CoddyKit 上的免费 AI SaaS Builder 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 AI SaaS Builder 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI SaaS Builder 课程共包含 4 节课。

API：应用程序的通信纽带

在现代软件中，应用程序的不同部分通常需要相互通信。对于 AI SaaS 来说尤其如此，因为您的前端（用户看到的部分）需要与功能强大的 AI 后端进行交互。

应用程序接口（API）就像餐厅的菜单。菜单列出您可以点的菜品（函数），并说明您需要提供哪些原料（参数），以及最后会得到什么（结果）。

对于 Web 应用程序而言，RESTful API 是前端和后端系统通过互联网通信的最常用方式。

什么是 REST？

REST 是表述性状态转移（Representational State Transfer）的缩写。它是一种架构风格，而不是协议，用于定义设计 Web 服务的一组约束。

您可以把它理解为后端向其他应用程序提供服务的蓝图。遵循 REST 原则可以使 API 具备以下特点：

  • 可扩展：能够处理更多请求。
  • 灵活：易于演进和适应变化。
  • 易维护：更易于理解和修复。

其核心思想是将所有内容视为“资源”。

REST 的核心原则

REST 依靠多个关键原则来实现上述优势：

  • 客户端-服务器：分离关注点。客户端负责处理用户界面，服务器负责数据存储和处理。
  • 无状态：客户端发送给服务器的每个请求都必须包含理解该请求所需的全部信息。服务器不会在请求之间保存任何客户端上下文。
  • 可缓存：可以将响应标记为可缓存，以提升性能。
  • 统一接口：这是设计中最关键的原则。通过使用一致的资源交互方式，可以简化系统。

资源：API 中的名词

“统一接口”原则意味着您的 API 应该围绕资源展开。资源是任何可以命名的信息，例如用户、产品或订单。

进行设计时，请将资源视为名词而不是动词。您的 API 端点（URL）应该反映这些名词，通常使用复数形式。

  • 不要使用 /getUser，而应使用 /users
  • 不要使用 /createProduct，而应使用 /products
  • 不要使用 /deleteOrder/123，而应使用 /orders/123

这样可以使您的 API 直观且一致。

HTTP 方法：执行操作

拥有资源（例如 /products）后，您可以使用标准的 HTTP 方法对其执行操作。这些方法就像对应资源名词的动词。

  • GET：获取数据。（例如，使用 GET /products 获取所有产品）
  • POST：创建新数据。（例如，使用 POST /products 添加新产品）
  • PUT：更新或替换现有数据。（例如，使用 PUT /products/123 更新产品 123）
  • DELETE：删除数据。（例如，使用 DELETE /products/123 删除产品 123）

此外还有用于部分更新的 PATCH，但这四种方法最为基础。

示例：获取数据（GET）

让我们看看客户端如何使用 GET 方法与 RESTful API 交互，以获取数据。

这里，我们将从一个公开的测试 API 中获取一篇特定的帖子。URL /posts/1 清楚地标识了该资源。

import requests

# Define the API endpoint for a specific post
url = "https://jsonplaceholder.typicode.com/posts/1"

# Send a GET request
response = requests.get(url)

# Check if the request was successful (status code 200)
if response.status_code == 200:
  print("Successfully retrieved data:")
  print(response.json())
else:
  print(f"Error: {response.status_code} - {response.text}")

示例：创建数据（POST）

要创建新资源，我们使用 POST 方法。新数据会在请求正文中发送，通常采用 JSON 格式。

请注意，我们向复数形式的资源端点（/posts）发送请求时没有提供 ID，因为服务器会为其分配 ID。

import requests
import json

# Define the API endpoint for creating posts
url = "https://jsonplaceholder.typicode.com/posts"

# Define the data for the new post
new_post_data = {
  "title": "CoddyKit Lesson",
  "body": "This is a new post from CoddyKit!",
  "userId": 1
}

# Send a POST request with the JSON data
response = requests.post(url, json=new_post_data)

# Check if the request was successful (status code 201 Created)
if response.status_code == 201:
  print("Successfully created post:")
  print(response.json())
else:
  print(f"Error: {response.status_code} - {response.text}")

HTTP 状态码：API 的反馈

请求完成后，API 会返回一个 HTTP 状态码。这个三位数的代码会告诉客户端请求是否成功、是否发生错误以及错误类型。

  • 2xx 成功：200 OK（一般成功）、201 Created（资源已创建）、204 No Content（请求成功，但没有要返回的数据）。
  • 4xx 客户端错误：400 Bad Request（请求格式错误）、401 Unauthorized（缺少身份验证）、403 Forbidden（已通过身份验证但没有访问权限）、404 Not Found（资源不存在）。
  • 5xx 服务器错误：500 Internal Server Error（服务器发生错误）。

使用恰当的状态码对于设计良好的 API 至关重要。

数据格式：简洁的 JSON

在 RESTful API 之间传输数据时，常用的一种格式是 JSON（JavaScript 对象表示法）。

JSON 轻量、易于人类阅读，而且大多数编程语言都能轻松解析。它使用键值对和数组表示数据，因此非常适合结构化信息。

XML 曾经十分流行，但由于 JSON 简洁高效，如今 JSON 已成为 Web API 事实上的标准。

为 API 设置版本

随着您的 AI SaaS 不断发展，API 也会随之变化。您可能会添加新特征、改变数据结构，甚至移除旧端点。这正是API 版本管理发挥作用的地方。

版本管理可以让您在进行更改时，不会破坏依赖您 API 的现有应用程序。一种常见做法是将版本号加入 URL：

  • /v1/users（版本 1）
  • /v2/users（版本 2）

这样可以确保向后兼容，并让用户更平稳地完成过渡。

检查您的 API 设计技能

以下哪些是 RESTful API 设计的核心原则？

在交互式课程中回答

回顾：设计健壮的 API

恭喜您！您已经学习了设计 RESTful API 的基础知识。

  • API 支持前端和后端之间的通信。
  • REST 是一种强调资源和标准 HTTP 方法的架构风格。
  • 资源应在 URL 中通过复数名词进行标识。
  • HTTP 方法（GET、POST、PUT、DELETE）定义了对这些资源执行的操作。
  • HTTP 状态码会提供有关请求结果的重要反馈。
  • JSON 是 API 通信首选的数据格式。
  • API 版本管理可以确保平稳演进和向后兼容。

掌握这些概念是构建可扩展且易维护的 AI SaaS 后端的关键。

免费开始

用 AI 导师学习 AI SaaS Builder — 免费

在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。

课程
12
课程
47
免费开始学习查看完整课程

常见问题解答

「设计 RESTful API」课时是免费的吗？

是的 — 「设计 RESTful API」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI SaaS Builder 课程的其余内容，请升级到 CoddyKit PRO。 AI SaaS Builder 课程共包含 4 节课。

「设计 RESTful API」这节课中我会学到什么？

创建结构清晰且高效的 API，实现前端与后端之间的顺畅通信。 你通过在浏览器中直接运行的动手代码来练习 AI SaaS Builder，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI SaaS Builder 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI SaaS Builder 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。

「设计 RESTful API」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI SaaS Builder 课中编写并运行代码吗？

能。每节 AI SaaS Builder 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 设计 RESTful API
  2. SaaS 数据库管理
  3. 用户身份验证与授权
  4. 人工智能请求的速率限制与排队
← 返回 AI SaaS Builder