RESTful API 概览

REST (Representational State Transfer) 是一种基于 HTTP 协议的软件架构风格。本模块详细介绍了我们 RESTful API 的设计原则、标准规范及最佳实践。

设计原则

• 无状态性 (Stateless): 每个请求都必须包含处理该请求所需的全部信息，服务器不存储客户端的上下文。
• 资源导向 (Resource-Oriented): 所有的内容都被抽象为“资源”，通过唯一的 URL 进行访问。
• 统一接口 (Uniform Interface): 使用标准的 HTTP 方法（GET, POST, PUT, DELETE 等）来操作资源。

基础信息

Base URL

所有生产环境接口的根路径为：

``` https://api.example.com/v1 ```

版本控制

我们通过 URL 路径进行版本管理。当前稳定版本为 `v1`。

请求与响应格式

• 数据格式: 仅支持 `application/json`。
• 字符编码: 统一使用 `UTF-8`。