docs/CN/LLM-Hub/RESTful-API/RESTful-API.md

RESTful API（Representational State Transfer 风格的接口）是一种常见的 Web 服务设计规范，其核心思想和特点包括：

1. 资源（Resource）为中心

   • 把系统中的一切“对象”都看作资源，每个资源通过一个唯一的 URI（路径）来标识。
   • 例如：/models 可能对应“模型列表”资源，/models/123 对应“ID 为 123 的模型”资源。

2. 使用 HTTP 方法表示操作

   • GET：读取资源（不应改变服务器状态），
   • POST：创建资源，
   • PUT/PATCH：更新资源，
   • DELETE：删除资源。
     这样可以让接口语义清晰、与 HTTP 协议天然契合。

3. 无状态性（Stateless）

   • 每一次请求都包含完成该请求所需的所有信息，服务端不在请求之间保留客户端状态。
   • 优点是易于扩展与负载均衡；缺点是每次请求都要重复认证/传递上下文。

4. 表现层（Representation）

   • 客户端与服务端通过“表现层”交换资源状态，通常是 JSON、XML 或其他格式。
   • 比如 GET /models/123 返回如下 JSON：

     {
       "id": 123,
       "name": "gpt-4",
       "status": "deployed"
     }
     

5. 超媒体驱动（HATEOAS，可选）

   • 在响应中带上“链接”（links），告诉客户端可以做哪些后续操作，比如：

     {
       "id": 123,
       "links": [
         { "rel": "update", "href": "/models/123", "method": "PUT" },
         { "rel": "delete", "href": "/models/123", "method": "DELETE" }
       ]
     }
     

   • 这样客户端无须硬编码所有路径，能动态发现可用操作。

---

在 LLMHub 中的应用

在我们的 PRD 里，“统一抽象接口层”采用 RESTful API 设计，并以 OpenAPI 3.0 规范来描述，这意味着：

• 每个大模型相关的功能（列出模型、部署模型、调用模型）都被定义为一种资源操作；
• 开发者通过标准的 HTTP 方法和约定好的路径，就能对接各种底层模型平台；
• 文档会自动生成（Swagger UI），并确保接口清晰、一致且易于测试。

这样，无论后端具体集成了哪家大模型服务，上层调用逻辑都保持不变——真正达到了“屏蔽底层差异、统一使用体验”的目标。