REST（Representational State Transfer）把业务对象看作资源（Resource）：用 URL 定位资源，用 GET、POST、PUT、PATCH、DELETE 等 HTTP 方法表达读取与变更。响应体多用 JSON，状态码表达成功、客户端错误或服务端错误。它之所以流行，是因为约定直观、调试工具完善、与 Web 基础设施天然契合。
常见约定
- 用名词路径表示资源，例如 /users、/orders/{id}
- 状态码区分成功与失败，避免「HTTP 200 但业务全错」却无说明
- JSON 作为主流交换格式，字段命名保持一致
- 无状态：每次请求自带鉴权与必要上下文，服务端不依赖隐藏会话
和 GraphQL 的差异
REST 端点相对固定，适合资源边界清晰的业务；GraphQL 常集中在一个端点，由客户端声明字段，适合复杂嵌套查询。选型应看团队熟悉度、缓存策略、监控成本与查询复杂度，而不是追潮流。
实践建议
设计时先画清资源与关系，再定错误模型与分页方式。版本策略（路径版本或头版本）要尽早明确。写好示例请求与边界条件，比空泛的「RESTful」口号更有用。联调阶段用 Postman 或 cURL 固化用例，能显著减少前后端扯皮。
文档与协作
给每个端点写清鉴权、分页、过滤与错误示例。评审接口时同步评审命名与资源边界。前后端用同一份示例请求对齐预期，能减少联调轮次。变更若无法向后兼容，尽早沟通迁移窗口与兼容策略。
把错误响应格式统一，并在文档里给出可复制的失败样例。监控时按端点与状态码聚合，比只看总成功率更容易定位问题。REST 写得清楚，后续换成网关或服务网格也会更轻松。