LilyTech

RESTful API 是什么?请求与响应实例解析

Nguyễn Chính Ngọc Liên审核Hoàng Linh内容管理Lê Mạnh

RESTful API 是什么?通过在线点餐实例了解请求与响应的实际流程

点餐应用显示菜品列表、提交订单并更新配送状态时,后台的不同软件需要彼此交换数据。RESTful API 是一种设计这类交互接口的方式,能够让应用按照明确的约定向服务器发送请求并接收数据。

本文中,LilyTech 将介绍 RESTful API 是什么,讲解如何理解 endpoint 结构,并通过在线点餐场景说明常见 HTTP 方法。借助 JSON 请求与响应示例,您可以直观了解 API 在实际应用中的工作方式。

RESTful API 是什么?

API 是 Application Programming Interface(应用程序编程接口)的缩写,用于规定一款软件如何向另一款软件请求功能或数据。例如,手机应用可以调用 API 从服务器获取菜单,无须了解系统内部如何存储数据。

开发人员讨论 RESTful API 以及应用如何连接服务器
RESTful API 通过资源、endpoint 和请求,为应用与服务器之间的数据交换建立约定。

REST 是 Representational State Transfer(表述性状态转移)的缩写,是一种用于设计 Web 服务的架构风格。API 在一定程度上遵循 REST 原则构建时,通常称为 RESTful API。在实际使用中,人们常用“RESTful API”指通过 HTTP 交换资源的 Web API,通常以 JSON 格式发送和接收数据。

在这种模式下,数据会被表示为资源,例如菜品、客户或订单。每个资源通常有自己的地址,称为 endpoint。应用通过 HTTP 方法向 endpoint 发送 request;服务器处理请求后返回 response,通常包括状态码和所需数据。

RESTful API 不是一种编程语言,也不是某个具体产品,而是系统间组织通信的一种方式。借助一致的约定,开发团队可以更顺畅地构建 Web 应用、移动应用,或实现不同软件之间的集成。

Endpoint 结构与 API 请求

假设某在线点餐服务的 API 地址为 https://api.bepnhanh.vn。一个 request 通常包含 HTTP 方法、endpoint、header,也可能包含 body。Endpoint 用于明确指出应用希望访问的资源或执行的操作。

例如,endpoint /api/v1/menu-items 表示菜品列表。其中,/api 表示这是 API 路径,v1 表示版本,menu-items 则是资源组。另一个 endpoint 是 /api/v1/orders/5821,用于操作编号为 5821 的订单。

获取菜品列表的 request 可以表示如下:

方法与 endpoint: GET https://api.bepnhanh.vn/api/v1/menu-items?category=drink

Header: Accept: application/json

?category=drink 是 query parameter,用于按类别筛选菜品。Header 提供 request 的补充信息,例如应用可接受的数据格式或身份验证信息。创建订单时,request 通常还会包含用于传递 JSON 数据的 body。

清晰的 endpoint 命名有助于提升 API 的可读性和可扩展性。通常,资源名称采用名词形式,例如 /orders 或 /customers,而操作则由 HTTP 方法体现。这种约定可以避免为每种操作创建过多独立路径。

通过示例了解常见 HTTP 方法

HTTP 方法用于告诉服务器应用希望如何操作资源。RESTful API 中常见的方法包括 GET、POST、PUT、PATCH 和 DELETE。在点餐场景中,可以这样使用:

工程师团队结合订单处理流程分析 RESTful API 中的 HTTP 方法
GET、POST、PUT、PATCH 和 DELETE 等 HTTP 方法,帮助 RESTful API 表达对资源执行的操作。
  • GET – 读取数据:使用 GET /api/v1/menu-items 获取菜品列表,或使用 GET /api/v1/orders/5821 查看特定订单。GET 通常不发送用于创建或修改资源的数据。
  • POST – 创建资源:向 POST /api/v1/orders 发送菜品信息和配送地址,以创建新订单。处理成功后,服务器可以返回新建订单的编号。
  • PUT – 替换资源:向 PUT /api/v1/orders/5821 发送需要更新的完整信息。由于 PUT 通常表示替换,应用需要按照 API 要求提交完整字段。
  • PATCH – 部分更新:发送 PATCH /api/v1/orders/5821,仅更改订单状态或配送地址,而无须重新提交整张订单。
  • DELETE – 删除资源:发送 DELETE /api/v1/orders/5821 请求删除或取消订单,具体取决于系统策略。

每种操作的具体含义取决于 API 文档。例如,某个系统可能不允许删除已付款订单,只允许将其状态改为“已取消”。因此,应用端需要遵循服务器公布的业务规则。

实际 JSON 请求与响应示例

假设客户订购两杯咖啡,并要求配送到已选地址。应用会向创建订单的 endpoint 发送 POST request。Body 可以包含菜品编号、数量和配送信息,例如:

工程师检查点餐应用中 RESTful API 的 JSON 请求与响应
JSON 请求与响应示例展示了 API 如何接收订单信息、处理请求,并返回订单编号和状态。

Request: POST /api/v1/orders

Header: Content-Type: application/json; Authorization: Bearer <access_token>

Body: {"items": [{"menu_item_id": 42, "quantity": 2}], "delivery_address_id": 918, "note": "少冰"}

Content-Type header 表示 body 以 JSON 格式发送。Authorization header 携带身份验证信息,让服务器确认下单用户的身份。在实际系统中,应妥善保护 access token,并通过安全连接发送;不要将敏感信息放在 URL 中。

如果订单创建成功,服务器可能返回如下 response:

Response: HTTP 201 Created

Body: {"id": 5821, "status": "pending_confirmation", "total": 98000, "currency": "VND", "created_at": "2025-03-08T10:15:00Z"}

201 Created 状态码表示新资源已创建。返回的数据包括订单编号、状态、总金额和创建时间。应用可以使用订单编号 5821 跳转到订单跟踪页面。

如果应用调用 GET /api/v1/orders/5821,服务器可能会返回 HTTP 200 OK 以及订单数据。status 字段会随处理进度变化,例如从 pending_confirmation 变为 preparing,再变为 delivering。如果订单编号不存在,服务器可能返回 404 Not Found;如果用户尚未登录或 token 无效,则可能返回 401 Unauthorized。

状态码能帮助应用判断 request 是成功还是出错,无须根据 JSON 内容进行猜测。常见状态码包括:200 表示处理成功,400 表示提交的数据无效,403 表示权限不足,404 表示找不到资源,500 表示服务器发生错误。

设计与集成 RESTful API 时的注意事项

为了便于理解,上述示例简化了一些细节。将 API 用于实际产品时,企业和开发团队应从一开始就统一数据约定、错误处理和安全规则。这些决策会直接影响系统的集成与维护能力。

  • 保持 endpoint 设计一致:使用易懂的资源名称,必要时划分版本,并统一数据字段的命名方式。
  • 返回有用的错误信息:提供合适的状态码和足够清晰的提示,方便开发人员处理,同时避免泄露敏感的内部信息。
  • 保护数据:使用 HTTPS,对用户进行身份验证,按角色分配权限,并在处理前检查输入数据。
  • 管理性能:对于大型列表,支持分页、筛选或限制结果数量;同时考虑限制调用频率,以降低系统过载风险。
  • 编写文档并进行测试:说明 endpoint、方法、参数、response 以及可能出现的错误,帮助开发团队准确完成集成。

当企业需要连接网站、移动应用、管理系统或合作伙伴服务时,RESTful API 通常是合适的选择。不过,架构选择仍需结合数据、性能、安全和运维能力等要求。优秀的 API 设计不只是规划合理的 URL,还需要准确反映企业的业务流程。

总结:理解 RESTful API,让系统连接更高效

RESTful API 是一种通过资源、endpoint 和 HTTP 方法组织应用间通信的方式。了解 GET 如何获取数据、POST 如何创建订单、PUT 或 PATCH 如何更新资源,以及 DELETE 如何删除资源后,您就能更轻松地理解数字产品中的 request–response 流程。JSON 结构和状态码让数据交换遵循明确约定,便于开发与集成。

如果企业正在建设网站或移动应用,或需要将 API 与 ERP 及现有系统连接,LilyTech 可以根据运营流程提供合适的解决方案。欢迎联系 LilyTech,沟通您的需求并探讨高效的实施方向。

关于作者

Nguyễn Chính Ngọc Liên

Nguyễn Chính Ngọc Liên tốt nghiệp Đại học Công nghiệp và có 7 năm kinh nghiệm trong lĩnh vực viết nội dung SEO. Với nền tảng kiến thức chuyên môn cùng kinh nghiệm thực tế, Ngọc Liên tập trung xây dựng những nội dung rõ ràng, hữu ích, chuẩn SEO và đáp ứng nhu cầu tìm kiếm của người đọc.