点餐应用显示菜品列表、提交订单并更新配送状态时,后台的不同软件需要彼此交换数据。RESTful API 是一种设计这类交互接口的方式,能够让应用按照明确的约定向服务器发送请求并接收数据。
本文中,LilyTech 将介绍 RESTful API 是什么,讲解如何理解 endpoint 结构,并通过在线点餐场景说明常见 HTTP 方法。借助 JSON 请求与响应示例,您可以直观了解 API 在实际应用中的工作方式。
RESTful API 是什么?
API 是 Application Programming Interface(应用程序编程接口)的缩写,用于规定一款软件如何向另一款软件请求功能或数据。例如,手机应用可以调用 API 从服务器获取菜单,无须了解系统内部如何存储数据。

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。在点餐场景中,可以这样使用:

- 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 可以包含菜品编号、数量和配送信息,例如:

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

