我 总 结 了 22 条 API 设 计 的 最 佳 实 践

Wed 29 September 2021

在 这 个 微 服 务 的 世 界 里 , 后 端 API 的 一 致 性 设 计 是 必 不 可 少 的 。

令 天 , 我 们 将 讨 论 一 些 可 遵 循 的 最 佳 实 践 。 我 们 将 保 持 简 短 和 甜 蜜 一 一 所 以 系 好 安 全 带 , 出 发 咯 !

首 先 介 绍 一 些 术 语

任 何 API 设 计 都 遵 循 一 种 叫 做 “ 面 向 资 源 设 计 “ 的 原 则 :

。 资 源 : 资 源 是 数 据 的 一 部 分 , 例 如 : 用 户 。 集 合 : 一 组 资 源 称 为 集 合 , 例 如 : 用 户 列 表 。 URL: 标 识 资 源 或 集 合 的 位 置 , 例 如 : /user 。 资 源 : 资 源 是 数 据 的 一 部 分 , 例 如 : 用 户 。 集 合 : 一 组 资 源 称 为 集 合 , 例 如 : 用 户 列 表 。 URL: 标 识 资 源 或 集 合 的 位 置 , 例 如 : /user

  1. 对 URL 使 用 kebab-case ( 短 横 线 小 写 隔 开 形 式 )

例 如 , 如 果 你 想 要 获 得 订 单 列 表 。

不 应 该 :

/systemorders 或 system_orders

应 该 :

/system-orders /system-orders

  1. 参 数 使 用 camelCase ( 驼 峰 形 式 )

例 如 , 如 果 你 想 从 一 个 特 定 的 商 店 购 买 产 品 。

不 应 该 :

/system-orders/ {torder_id}

或 者 :

/system-orders/ {0rderId} /system-orders/torderld}

  1. 指 向 集 合 的 复 数 名 称

如 果 你 想 获 得 系 统 的 所 有 用 户 。

不 应 该 :

GET /user

或 :

GET /User

应 该 : GET /users

  1. URL 以 集 合 开 始 , 以 标 识 符 结 束

如 果 要 保 持 概 念 的 单 一 性 和 一 致 性 。

不 应 该 :

GET /shops/ :shopId/category/:categoryId/price

这 很 糟 糕 , 因 为 它 指 向 的 是 一 个 属 性 而 不 是 资 源 。

应 该 :

GET /shops/:shopld/ 或 GET /category/:categoryld

5 年刊 讥 训 姜 你 的 资 江 JR| 不 要 在 URL 中 使 用 动 词 来 表 达 你 的 意 图 。 相 反 , 使 用 适 当 的 HTTP 方 法 来 描 述 操 作 。

不 应 该 :

P0ST /updateuser/ {userId} 或 :

GET /getusers

应 该 :

PUT /user/tuserld}

  1. 对 非 资 源 URL 使 用 动 词 PUT /user/tuserld}

  2. 对 非 资 源 URL 使 用 动 词

如 果 你 有 一 个 端 点 , 它 只 返 回 一 个 操 作 。 在 这 种 情 况 下 , 你 可 以 使 用 动 词 。 例 如 , 如 果 你 想 要 向 用 户 重 新 发 送 警 报 。

应 该 :

POST /alarm/245743/resend

请 记 住 , 这 些 不 是 我 们 的 CRUD 操 作 。 相 反 , 它 们 被 认 为 是 在 我 们 的 系 统 中 执 行 特 定 工 作 的 函 数 。

  1. JSON 属 性 使 用 camelCase 驼 峰 形 式 如 果 佣 正 在 构 建 一 个 请 求 体 或 响 应 体 为 JSON 的 系 统 , 那 么 属 性 名 应 该 使 用 驼 峰 大 小 写 。

不 应 该 :

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 端 点 。

  1. 不 要 使 用 table_name 作 为 资 源 名

不 要 只 使 用 表 名 作 为 资 源 名 。 从 长 远 来 看 , 这 种 懒 惰 是 有 害 的 。 不 应 该 : 9. 不 婉 使 用 table_nameffF 力 货 源 名

不 要 只 使 用 表 名 作 为 资 源 名 。 从 长 远 来 看 , 这 种 懒 惰 是 有 害 的 。 不 应 该 :

product_order

应 该 :

product-orders

这 是 因 为 公 开 底 层 体 系 结 构 不 是 你 的 目 的 。

  1. 使 用 API 设 计 工 具 C BCG I - 一 K

有 许 多 好 的 API 设 计 工 具 用 于 编 写 好 的 文 档 , 例 如 :

s APlI 蓝 图 : https://apiblueprint.org/

Swagger: https://swagger.io

拥 有 良 好 而 详 细 的 文 档 可 以 为 API 使 用 者 带 来 良 好 的 用 户 体 验 。

  1. 使 用 简 单 序 数 作 为 版 本

始 终 对 API 使 用 版 本 控 制 , 并 将 其 向 左 移 动 , 使 其 具 有 最 大 的 作 用 域 。 版 本 号 应 该 是 v1,v2 等 等 。

应 该 : http://apidomain.com/v1/shops/3/products 心 医 川 团 中 厌 友 止 月 队 个

始 终 对 API 使 用 版 本 控 制 , 并 将 其 向 左 移 动 , 使 其 具 有 最 大 的 作 用 域 。 版 本 号 应 该 是 v1,v2 等 等 。

应 该 : http://apidomain.com/v1/shops/3/products

始 终 在 API 中 使 用 版 本 控 制 , 因 为 如 果 API 被 外 部 实 体 使 用 , 更 改 端 点 可 能 会 破 坏 它 们 的 功 能 。

  1. 在 你 的 响 应 体 中 包 括 总 资 源 数

如 果 API 返 回 一 个 对 象 列 表 , 则 响 应 中 总 是 包 含 资 源 的 总 数 。 你 可 以 为 此 使 用 total 属 性 。

不 应 该 : “ 人 C 万 CH VGA H 女

如 果 API 返 回 一 个 对 象 列 表 , 则 响 应 中 总 是 包 含 资 源 的 总 数 。 你 可 以 为 此 使 用 total 属 性 。

不 应 该 :

total: 34

  1. 接 受 limit 和 offset 参 数 在 GET 操 作 中 始 终 接 受 limit 和 offset 参 数 。 应 该 :

GET /shops?offset=5&limit=5

这 是 因 为 它 对 于 前 端 的 分 页 是 必 要 的 。

  1. 获 取 字 段 查 询 参 数

o 添 加 一 个 fields 参 数 , 只 公 开 API 中 必 需 时 字 段 。

例 子 : 只 返 回 商 店 的 名 称 , 地 址 和 联 系 方 式 。

ET lehnna?fialda-irl nama arlriraca Phntar+

o 添 加 一 个 fields 参 数 , 只 公 开 API 中 必 需 时 字 段 。

例 子 : 只 返 回 商 店 的 名 称 , 地 址 和 联 系 方 式 。

GET /shops?fields=id,name,address,contact

在 某 些 情 况 下 , 它 还 有 助 于 减 少 响 应 大 小 。

  1. 不 要 在 URL 中 通 过 认 证 令 牌

这 是 一 种 非 常 糟 糕 的 做 法 , 因 为 url 经 常 被 记 录 , 而 身 份 验 证 令 牌 也 会 被 不 必 要 地 记 录 。

不 应 该 : 这 是 一 种 非 常 糟 糕 的 做 法 , 因 为 url 经 常 被 记 录 , 而 身 份 验 证 令 牌 也 会 被 不 必 要 地 记 录 。

不 应 该 :

GET /shops/123?token=some_kind_of _authenticaiton_token

相 反 , 通 过 头 部 传 递 它 们 :

Authorization: Bearer XxXXXX, Extra yyyYy

此 外 , 授 权 令 牌 应 该 是 短 暂 有 效 期 的 。

心

  1. 验 证 内 容 类 型

服 务 器 不 应 该 假 定 内 容 类 型 。 例 如 , 如 果 你 接 受 application/x-www- 服 务 器 不 应 该 假 定 内 容 类 型 。 例 如 , 如 果 你 接 受 application/x-www- 0 那 么 攻 击 者 可 以 创 建 一 个 表 单 并 触 发 一 个 简 单 的 请 求 。

因 此 , 始 终 验 证 内 容 类 型 , 如 果 你 想 使 用 默 认 的 内 容 类 型 , 请 使 用 :

content-type: application/json

  1. 对 CRUD 国 数 使 用 HTTP 方 法

HTTP 方 法 用 于 解 释 CRUD 功 能 。

GET: 检 索 资 源 的 表 示 形 式 。

POST: 创 建 新 的 资 源 和 子 资 源 。

PUT: 更 新 现 有 资 源 。

PATCH: 更 新 现 有 资 源 , 它 只 更 新 提 供 的 字 段 , 而 不 更 新 其 他 字 段 。 DELETE: 删 除 已 存 在 的 资 源 。 HTTP 万 法 用 于 解 释 CRUD 功 能 。

GET: 检 索 资 源 的 表 示 形 式 。

POST: 创 建 新 的 资 源 和 子 资 源 。

PUT: 更 新 现 有 资 源 。

PATCH: 更 新 现 有 资 源 , 它 只 更 新 提 供 的 字 段 , 而 不 更 新 其 他 字 段 。 DELETE: 删 除 已 存 在 的 资 源 。

  1. 在 嵌 套 资 源 的 URL 中 使 用 关 系

以 下 是 一 些 实 际 例 子 :

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。

  1. CORS ( 跨 源 资 源 共 享 )

一 定 要 为 所 有 面 向 公 共 的 API 支 持 CORS ( 跨 源 资 源 共 享 ) 头 部 。 考 虑 支 持 CORS 允 许 的 “““ 来 源 , 并 通 过 有 效 的 OAuth 令 牌 强 制 授 权 。 避 免 将 用 户 凭 证 与 原 始 验 证 相 结 合 。 一 定 要 为 所 有 面 向 公 共 的 API 支 持 CORS ( 跨 源 资 源 共 享 ) 头 部 。 考 虑 支 持 CORS 允 许 的 “““ 来 源 , 并 通 过 有 效 的 OAuth 令 牌 强 制 授 权 。 避 免 将 用 户 凭 证 与 原 始 验 证 相 结 合 。

  1. 安 全

在 所 有 端 点 、 资 源 和 服 务 上 实 施 HTTPS (tls 加 密 ) 。 强 制 并 要 求 所 有 回 调 url、 推 送 通 知 端 点 和 webhooks 使 用 HTTPS。

  1. 错 误

当 客 户 端 向 服 务 发 出 无 效 或 不 正 确 的 请 求 , 或 向 服 务 传 递 无 效 或 不 正 确 的 数 据 , 而 服 务 拒 绝 该 请 求 时 , 就 会 出 现 错 误 , 或 者 更 具 体 地 说 , 出 现 当 客 户 端 向 服 务 发 出 无 效 或 不 正 确 的 请 求 , 或 向 服 务 传 递 无 效 或 不 正 确 [ 沥 才 毕 工 子 EE 就 会 出 现 错 误 , 或 者 更 具 体 地 说 , 出 现 力

误 。

例 子 包 括 无 效 的 身 份 验 证 凭 证 、 不 正 确 的 参 数 、 未 知 的 版 本 id 等 。

。 当 由 于 一 个 或 多 个 服 务 错 误 而 拒 绝 客 户 端 请 求 时 , 一 定 要 返 回 4xx HTTP 错 误 代 码 。

。 考 虑 处 理 所 有 属 性 , 然 后 在 单 个 响 应 中 返 回 多 个 验 证 问 题 。

  1. 黄 金 法 则

e 这 些 黄 金 规 则 可 以 帮 助 我 们 做 出 正 确 决 定 。

。 扁 平 比 嵌 套 好 。

。 简 单 胜 于 复 杂 。 。 字 符 串 比 数 字 好 。 22. 黄 金 法 则 e 这 些 黄 金 规 则 可 以 帮 助 我 们 做 出 正 确 决 定 。

。 扁 平 比 嵌 套 好 。

。 简 单 胜 于 复 杂 。 字 符 串 比 数 字 好 。 。 一 致 性 比 定 制 更 好 。

黄 是 这 样 一 如 果 你 已 经 走 到 了 这 一 步 , 恭 喜 你 ! 希 望 你 学 到 了 一 些 东

希 望 你 度 过 美 好 的 一 天 !

原 文 链 接 : https://betterprogramming.pub/22-best-practices-to- take-your-api-design-skills-to-the-next-Ilevel-65569b200b9 转 载 自 https:/jImp.weixin.qq.com/s/doQsjLpZ4F68GtK7XR5QDQ, 刘 志 超 译

Category: 杂物