60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
---
|
||
title: API 准则
|
||
description: 在设计 Solar Network 服务 API 时惯用的准则
|
||
published: true
|
||
date: 2024-08-18T05:46:02.121Z
|
||
tags: solar network
|
||
editor: markdown
|
||
dateCreated: 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`，一行简单的文字来代表你犯了什么错。
|
||
|
||
如果你是英语白痴，遇到报错别老来问我们，用用翻译好吗？不然我们写报错信息干嘛。 |