| modified | Thursday 1 May 2025 |
|---|
Wednesday, September 29, 2021 at 09:27
我 总 结 了 22 条 API 设 计 的 最 佳 实 践
anZhihe
安 志 合 的 学 习 博 客
曾 经 因 为 一 个 糟 糕 的 API 而 感 到 沮 丧 吗 ?
在 这 个 微 服 务 的 世 界 里 , 后 端 API 的 一 致 性 设 计 是 必 不 可 少 的 。
令 天 , 我 们 将 讨 论 一 些 可 遵 循 的 最 佳 实 践 。 我 们 将 保 持 简 短 和 甜 蜜 一 一
所 以 系 好 安 全 带 , 出 发 咯 !
首 先 介 绍 一 些 术 语
任 何 API 设 计 都 遵 循 一 种 叫 做 “ 面 向 资 源 设 计 “ 的 原 则 :
。 资 源 : 资 源 是 数 据 的 一 部 分 , 例 如 : 用 户
。 集 合 : 一 组 资 源 称 为 集 合 , 例 如 : 用 户 列 表
。 URL: 标 识 资 源 或 集 合 的 位 置 , 例 如 : /user
。 资 源 : 资 源 是 数 据 的 一 部 分 , 例 如 : 用 户
。 集 合 : 一 组 资 源 称 为 集 合 , 例 如 : 用 户 列 表
。 URL: 标 识 资 源 或 集 合 的 位 置 , 例 如 : /user
例 如 , 如 果 你 想 要 获 得 订 单 列 表 。
不 应 该 :
/systemorders 或 system_orders
应 该 :
/system-orders
/system-orders
例 如 , 如 果 你 想 从 一 个 特 定 的 商 店 购 买 产 品 。
不 应 该 :
/system-orders/ {torder_id}
或 者 :
/system-orders/ {0rderId}
/system-orders/torderld}
如 果 你 想 获 得 系 统 的 所 有 用 户 。
不 应 该 :
GET /user
或 :
GET /User
应 该 :
GET /users
如 果 要 保 持 概 念 的 单 一 性 和 一 致 性 。
不 应 该 :
GET /shops/ :shopId/category/:categoryId/price
这 很 糟 糕 , 因 为 它 指 向 的 是 一 个 属 性 而 不 是 资 源 。
应 该 :
GET /shops/:shopld/ 或 GET /category/:categoryld
5 年刊 讥 训 姜 你 的 资 江 JR|
不 要 在 URL 中 使 用 动 词 来 表 达 你 的 意 图 。 相 反 , 使 用 适 当 的 HTTP 方 法
来 描 述 操 作 。
不 应 该 :
P0ST /updateuser/ {userId}
或 :
GET /getusers
应 该 :
PUT /user/tuserld}
对 非 资 源 URL 使 用 动 词
PUT /user/tuserld}
对 非 资 源 URL 使 用 动 词
如 果 你 有 一 个 端 点 , 它 只 返 回 一 个 操 作 。 在 这 种 情 况 下 , 你 可 以 使 用 动
词 。 例 如 , 如 果 你 想 要 向 用 户 重 新 发 送 警 报 。
应 该 :
POST /alarm/245743/resend
请 记 住 , 这 些 不 是 我 们 的 CRUD 操 作 。 相 反 , 它 们 被 认 为 是 在 我 们 的 系
统 中 执 行 特 定 工 作 的 函 数 。
不 应 该 :
user_name: “Mohammad Faisal“
user_id: “1“
userName: “Mohammad Faisal“
userIQ: “1“
RESTful HTTP 服 务 必 须 实 现 /health 和 /version 和 /metricsAPI 端 点 。 他 们
将 提 供 以 下 信 息
/CAo
/health
用 200 OK 状 态 码 响 应 对 /health 的 请 求 。
/Nersion
用 版 本 号 响 应 对 /version 的 请 求 。
/metrics
这 个 端 点 将 提 供 各 种 指 标 , 如 平 均 响 应 时 间 。
也 强 烈 推 荐 使 用 /debug 和 /status 端 点 。
不 要 只 使 用 表 名 作 为 资 源 名 。 从 长 远 来 看 , 这 种 懒 惰 是 有 害 的 。
不 应 该 :
9. 不 婉 使 用 table_nameffF 力 货 源 名
不 要 只 使 用 表 名 作 为 资 源 名 。 从 长 远 来 看 , 这 种 懒 惰 是 有 害 的 。
不 应 该 :
product_order
应 该 :
product-orders
这 是 因 为 公 开 底 层 体 系 结 构 不 是 你 的 目 的 。
有 许 多 好 的 API 设 计 工 具 用 于 编 写 好 的 文 档 , 例 如 :
s APlI 蓝 图 : https://apiblueprint.org/
Swagger: https://swagger.io
拥 有 良 好 而 详 细 的 文 档 可 以 为 API 使 用 者 带 来 良 好 的 用 户 体 验 。
始 终 对 API 使 用 版 本 控 制 , 并 将 其 向 左 移 动 , 使 其 具 有 最 大 的 作 用 域 。
版 本 号 应 该 是 v1,v2 等 等 。
应 该 : http://apidomain.com/v1/shops/…
心 医 川 团 中 厌 友 止 月 队 个
始 终 对 API 使 用 版 本 控 制 , 并 将 其 向 左 移 动 , 使 其 具 有 最 大 的 作 用 域 。
版 本 号 应 该 是 v1,v2 等 等 。
应 该 : http://apidomain.com/v1/shops/…
始 终 在 API 中 使 用 版 本 控 制 , 因 为 如 果 API 被 外 部 实 体 使 用 , 更 改 端 点 可
能 会 破 坏 它 们 的 功 能 。
如 果 API 返 回 一 个 对 象 列 表 , 则 响 应 中 总 是 包 含 资 源 的 总 数 。 你 可 以 为
此 使 用 total 属 性 。
不 应 该 :
“ 人 C 万 CH VGA H 女
如 果 API 返 回 一 个 对 象 列 表 , 则 响 应 中 总 是 包 含 资 源 的 总 数 。 你 可 以 为
此 使 用 total 属 性 。
不 应 该 :
total: 34
GET /shops?offset=5&limit=5
这 是 因 为 它 对 于 前 端 的 分 页 是 必 要 的 。
o 添 加 一 个 fields 参 数 , 只 公 开 API 中 必 需
时 字 段 。
例 子 :
只 返 回 商 店 的 名 称 , 地 址 和 联 系 方 式 。
ET lehnna?fialda-irl nama arlriraca Phntar+
o 添 加 一 个 fields 参 数 , 只 公 开 API 中 必 需
时 字 段 。
例 子 :
只 返 回 商 店 的 名 称 , 地 址 和 联 系 方 式 。
GET /shops?fields=id,name,address,contact
在 某 些 情 况 下 , 它 还 有 助 于 减 少 响 应 大 小 。
这 是 一 种 非 常 糟 糕 的 做 法 , 因 为 url 经 常 被 记 录 , 而 身 份 验 证 令 牌 也 会
被 不 必 要 地 记 录 。
不 应 该 :
这 是 一 种 非 常 糟 糕 的 做 法 , 因 为 url 经 常 被 记 录 , 而 身 份 验 证 令 牌 也 会
被 不 必 要 地 记 录 。
不 应 该 :
GET /shops/123?token=some_kind_of _authenticaiton_token
相 反 , 通 过 头 部 传 递 它 们 :
Authorization: Bearer XxXXXX, Extra yyyYy
此 外 , 授 权 令 牌 应 该 是 短 暂 有 效 期 的 。
心
服 务 器 不 应 该 假 定 内 容 类 型 。 例 如 , 如 果 你 接 受 application/x-www-
服 务 器 不 应 该 假 定 内 容 类 型 。 例 如 , 如 果 你 接 受 application/x-www-
0 那 么 攻 击 者 可 以 创 建 一 个 表 单 并 触 发 一 个 简 单 的
请 求 。
因 此 , 始 终 验 证 内 容 类 型 , 如 果 你 想 使 用 默 认 的 内 容 类 型 , 请 使 用 :
content-type: application/json
HTTP 方 法 用 于 解 释 CRUD 功 能 。
GET: 检 索 资 源 的 表 示 形 式 。
POST: 创 建 新 的 资 源 和 子 资 源 。
PUT: 更 新 现 有 资 源 。
PATCH: 更 新 现 有 资 源 , 它 只 更 新 提 供 的 字 段 , 而 不 更 新 其 他 字 段 。
DELETE: 删 除 已 存 在 的 资 源 。
HTTP 万 法 用 于 解 释 CRUD 功 能 。
GET: 检 索 资 源 的 表 示 形 式 。
POST: 创 建 新 的 资 源 和 子 资 源 。
PUT: 更 新 现 有 资 源 。
PATCH: 更 新 现 有 资 源 , 它 只 更 新 提 供 的 字 段 , 而 不 更 新 其 他 字 段 。
DELETE: 删 除 已 存 在 的 资 源 。
以 下 是 一 些 实 际 例 子 :
s GET /shops/2/products: 从 shop 2 获 取 所 有 产 品 的 列 表 。
@ i 获 取 产 品 31 的 详 细 信 息 , 产 品 31 属 于
shop 2
s DELETE /shops/2/products/31: 应 该 删 除 产 品 31, 它 属 于 商 店 2。
s PUT /shops/2/products/31: 应 该 更 新 产 品 31 的 信 息 , 只 在
resource-URL 上 使 用 PUT, 而 不 是 集 合 。
以 下 是 一 些 实 际 例 子 :
GET /shops/2/products: 从 shop 2 获 取 所 有 产 品 的 列 表 。
@ i 获 取 产 品 31 的 详 细 信 息 , 产 品 31 属 于
Sshop 2
DELETE /shops/2/products/31: 应 该 删 除 产 品 31, 它 属 于 商 店 2。
PUT /shops/2/products/31: 应 该 更 新 产 品 31 的 信 息 , 只 在
resource-URL 上 使 用 PUT, 而 不 是 集 合 。
。 POSTL/ahops: 应 该 创 建 一 个 新 的 商 店 , 并 返 回 创 建 的 新 商 店 的
详 细 信 息 。 在 集 合 url 上 使 用 POST。
一 定 要 为 所 有 面 向 公 共 的 API 支 持 CORS ( 跨 源 资 源 共 享 ) 头 部 。
考 虑 支 持 CORS 允 许 的 “““ 来 源 , 并 通 过 有 效 的 OAuth 令 牌 强 制 授 权 。
避 免 将 用 户 凭 证 与 原 始 验 证 相 结 合 。
一 定 要 为 所 有 面 向 公 共 的 API 支 持 CORS ( 跨 源 资 源 共 享 ) 头 部 。
考 虑 支 持 CORS 允 许 的 “““ 来 源 , 并 通 过 有 效 的 OAuth 令 牌 强 制 授 权 。
避 免 将 用 户 凭 证 与 原 始 验 证 相 结 合 。
在 所 有 端 点 、 资 源 和 服 务 上 实 施 HTTPS (tls 加 密 ) 。
强 制 并 要 求 所 有 回 调 url、 推 送 通 知 端 点 和 webhooks 使 用 HTTPS。
当 客 户 端 向 服 务 发 出 无 效 或 不 正 确 的 请 求 , 或 向 服 务 传 递 无 效 或 不 正 确
的 数 据 , 而 服 务 拒 绝 该 请 求 时 , 就 会 出 现 错 误 , 或 者 更 具 体 地 说 , 出 现
当 客 户 端 向 服 务 发 出 无 效 或 不 正 确 的 请 求 , 或 向 服 务 传 递 无 效 或 不 正 确
[ 沥 才 毕 工 子 EE 就 会 出 现 错 误 , 或 者 更 具 体 地 说 , 出 现
力
误 。
例 子 包 括 无 效 的 身 份 验 证 凭 证 、 不 正 确 的 参 数 、 未 知 的 版 本 id 等 。
。 当 由 于 一 个 或 多 个 服 务 错 误 而 拒 绝 客 户 端 请 求 时 , 一 定 要 返 回 4xx
HTTP 错 误 代 码 。
。 考 虑 处 理 所 有 属 性 , 然 后 在 单 个 响 应 中 返 回 多 个 验 证 问 题 。
e 这 些 黄 金 规 则 可 以 帮 助 我 们 做 出 正 确
决 定 。
。 扁 平 比 嵌 套 好 。
。 简 单 胜 于 复 杂 。
。 字 符 串 比 数 字 好 。
22. 黄 金 法 则
e 这 些 黄 金 规 则 可 以 帮 助 我 们 做 出 正 确
决 定 。
。 扁 平 比 嵌 套 好 。
。 简 单 胜 于 复 杂 。
字 符 串 比 数 字 好 。
。 一 致 性 比 定 制 更 好 。
黄 是 这 样 一 如 果 你 已 经 走 到 了 这 一 步 , 恭 喜 你 ! 希 望 你 学 到 了 一 些 东
希 望 你 度 过 美 好 的 一 天 !
原 文 链 接 : https://betterprogramming.pub/…
take-your-api-design-skills-to-the-next-Ilevel-65569b200b9
转 载 自 https:/jImp.weixin.qq.com/s/doQsjLpZ4F68GtK7XR5QDQ,
刘 志 超 译