Goatpedia/zh/solar-network/open/api-guide.md

title	description	published	date	tags	editor	dateCreated
API 准则	在设计 Solar Network 服务 API 时惯用的准则	true	2024-08-18T05:46:02.121Z	solar network	markdown	2024-08-18T05:46:02.121Z

这篇文章是关于我们平时在设计 Solar Network API 时的范式是怎样的，能够帮助你更好的调用我们的 API 来进行第二次开发

最小化

我们的 API 一般追求极简，不像某些大平台的 API 一样除了数据之外的格式还有一大堆什么状态码、信息、请求 ID 什么的。这些信息我们都选择放在 HTTP 的 Header 部分。HTTP 的响应体就是纯粹的数据，无其他信息（需要分页的数据接口会额外返回一个数据总数）。

增删查改

我们的 API 基本上都是遵循 RESTful 设计范式的，如果你不知道什么是 RESTful，可以看以下我们理解的实践的 RESTful

请求方法

• GET 查询
• POST 创建、进行某种操作
• PUT 更新（虽在 RESTful 中也被定义为创建数据的行为，但是我们不使用）
• PATCH 更新（不常用）
• DELETE 删除

路径映射

假如你 POST 了一个地址来创建数据，那么用 GET 方法访问相同的地址大概就是列出数据的列表。 在其后面加上 /<id> 就是单独读取某个数据，将请求方法改成 PUT 便是更新该条数据，改成 DELETE 就是删除该条数据。 如果在 /<id> 再加上东西基本上就是 POST 方法来执行某个操作。 例如以下是我们帖子的路径映射

注：:id 系路径参数

• GET /posts 获取帖子列表（分页）
• GET /posts/:id 获取单个帖子
• GET /posts/:id/replies 获取单个帖子的回复（分页）
• POST /posts 创建帖子（于新版本因为引入帖子类型移除，需使用对应类型的创建接口）
• PUT /posts/:id 更新帖子（于新版本因为引入帖子类型移除，需使用对应类型的更新接口）
• DELETE /posts/:id 删除帖子
• POST /posts/:id/pin 置顶帖子
• POST /posts/:id/react 对帖子作出反应

错误处理

我们不理解为什么 HTTP 有给一套完善的状态码系统，其他大厂却仍选择自立门户。关于响应的 HTTP 状态码，以下是一些常用的含义代表。

• 500 服务器内部错误 —— 你不用管，如果多见记得抛 issue
• 400 请求参数错误 —— 看文档，核查请求体
• 404 数据不存在或是接口路径不对
• 403 没有权限
• 200 成功
• 204 无内容 —— 常见于删除 虽然后时候写 API 会忘记删除内容时改成这个

如果响应不是 2xx 的状态码，一般我们都不会返回 application/json 的数据，而是一个 plain/text，一行简单的文字来代表你犯了什么错。

如果你是英语白痴，遇到报错别老来问我们，用用翻译好吗？不然我们写报错信息干嘛。