🙏废话不多说系列，直接开干🙏
一、总览
- 对URL使用kebab-case（短横线小写隔开形式）
- 参数使用camelCase（驼峰形式）
- 指向集合的复数名称
- URL以集合开始，以标识符结束
- 让动词远离你的资源URL
- 对非资源URL使用动词
- JSON属性使用camelCase驼峰形式
- 监控
- 不要使用table_name作为资源名
- 使用API设计工具
- 使用简单序数作为版本
- 在你的响应体中包括总资源数
- 接受limit和offset参数
- 获取字段查询参数
- 不要在URL中通过认证令牌
- 验证内容类型
- 对CRUD函数使用HTTP方法
- 在嵌套资源的URL中使用关系
- CORS（跨源资源共享）
- 安全
- 错误
- 黄金法则
二、详情
任何API设计都遵循一种叫做“面向资源设计”的原则：
- 资源：资源是数据的一部分，例如：用户
- 集合：一组资源称为集合，例如：用户列表
- URL：标识资源或集合的位置，例如：/user
（1）对 URL 使用 kebab-case(短横线小写隔开形式)
// 获取订单列表
// bad
/systemOrders 或 /system_orders
// good
/system-orders
（2）参数使用 camelCase（驼峰形式）
// 如果你想从一个特定的商店购买产品
// bad
/system-orders/{order_id} 或 /system-orders/{OrderId}
// good
/system-orders/{orderId}
（3）指向集合的复数名称
// 如果你想获得系统的所有用户。
// bad
GET /user 或 GET /User
// good
GET /users
（4）URL 以集合开始，标识符结束
// 如果要保持概念单一性和一致性
// bad(这很糟糕，因为它指向的是一个属性而不是资源。)
GET /shops/:shopId/category/:categoryId/price
// good（将其分成两个请求或重定义接口返回数据的结构）
GET /shops/:shopId 或 GET /category/:categoryId
（5）让动词远离你的资源 URL
// 不要在URL中使用动词来表达你的意图。相反，使用适当的HTTP方法来描述操作。
// bad
POST /updateuser/{userId} 或 GET /getusers
// good
PUT /user/{userId}
（6）对非资源URL使用动词
// 如果你有一个端点，它只返回一个操作。
// 在这种情况下，你可以使用动词。
// 例如：如果你想要向用户重新发送警报。
// good
POST /alarm/2345/resend
请记住，这些不是我们的CRUD操作。相反，它们被认为是在我们的系统中执行特定工作的函数。
（7）JSON 属性使用 camelCase 驼峰形式
如果你正在构建一个请求体或响应体为JSON的系统，那么属性名应该使用驼峰大小写。
// bad
{
user_name: "John Faisal",
user_id: "1"
}
// good
// bad
{
userName: "John Faisal",
userId: "1"
}
（8）监控
RESTful HTTP 服务必须实现 /health 和 /version 和 /metricsAPI 端点。他们将提供以下信息。
- /health：用200 OK状态码响应对 /health 的请求。
- /version：用版本号响应对 /version 的请求。
- /metrics：这个端点将提供各种指标，如 平均响应时间。
也强烈推荐使用 /debug 和 /status 端点。
（9）不要使用 table_name 作为资源名
不要只使用表名作为资源名。从长远来看，这种懒惰是有害的。
// bad
product_order
// good
product-orders
这是因为公开底层体系结构不是你的目的。
（10）使用 API 设计工具
有许多好的API设计工具用于编写好的文档，例如：
- API蓝图：apiblueprint.org/
- Swagger：swagger.io/
拥有良好而详细的文档可以为API使用者带来良好的用户体验。
（11）使用简单序数作为版本
始终对API使用版本控制，并将其向左移动，使其具有最大的作用域。版本号应该是v1，v2等等。
应该：http://api.domain.com/v1/shops/3/products
始终在API中使用版本控制，因为如果API被外部实体使用，更改端点可能会破坏它们的功能。
（12）在你的响应体中包括总资源数
如果 API 返回一个对象列表，则响应中总是包含资源的总数。你可以为此使用 total 属性。
// bad
{
users: [...]
}
// good
{
users: [...],
total: 34
}
（13）* 接受 limit 和 offset 参数
在 GET 操作中始终接受 limit 和 offset 参数。
// good（这是因为它对于前端的分页是必要的。）
GET /shops?offset=5&limit=3
（14）获取字段查询参数
返回的数据量也应该考虑在内。添加一个fields参数，只公开API中必需的字段。
// 例子：只返回商店的名称，地址和联系方式。
GET /shops?fields=id,name,address,contact
// 在某些情况下，它还有助于减少响应大小。
（15）不要在 URL 中通过认证令牌
这是一种非常糟糕的做法，因为url经常被记录，而身份验证令牌也会被不必要地记录。
// bad
GET /shops/123?token=some_kind_of_authentication_token
// good(通过头部传递它们)
Authorization: Bearer xxxxxx, Extra yyyyyy
// 此外，授权令牌应该是短暂有效期的。
（16）验证内容类型
服务器不应该假定内容类型。例如，如果你接受 application/x-www-form-urlencoded，那么攻击者可以创建一个表达并触发一个简单的POST请求。
因此，事中验证内容类型，如果你想使用默认的内容类型，请使用：
content-type: application/json
（17）对 CRUD 函数使用HTTP方法
HTTP 方法用于解释CRUD功能。
- GET：检索资源的表示形式。
- POST：创建新的资源和子资源。
- PUT：更新现有资源。
- PATCH：更新现有资源，它只更新提供的字段，而不更新其他字段。
- DELETE：删除已存在的资源。
（18）在嵌套资源的 URL 中使用关系
以下是一些实际例子：
GET /shops/2/products：从shop 2获取所有产品的列表。GET /shops/2/products/31：获取产品31的详细信息，产品31属于shop 2。DELETE /shops/2/products/31：应该删除产品31，它属于商店2。PUT /shops/2/products/31：应该更新产品31的信息，只在resource-URL上使用PUT，而不是集合。POST /shops：应该创建一个新的商店，并返回创建的新商店的详细信息。在集合url上使用POST。
（19）CORS（跨源资源共享）
一定要为所有面向公共的API支持CORS（跨源资源共享）头部。
考虑支持CORS允许的“*”来源，并通过有效的OAuth令牌强制授权。
避免将用户凭证与原始验证相结合。
（20）安全
在所有端点、资源和服务上实施HTTPS（tls加密）。
强制并要求所有回调url、推送通知端点和webhooks使用HTTPS。
（21）错误
当客户端向服务发出无效或不正确的请求，或向服务传递无效或不正确的数据，而服务拒绝该请求时，就会出现错误，或者更具体地说，出现服务错误。
例子包括无效的身份验证凭证、不正确的参数、未知的版本id等。
- 当由于一个或多个服务错误而拒绝客户端请求时，一定要返回4xx HTTP错误代码。
- 考虑处理所有属性，然后在单个响应中返回多个验证问题。
（22）♥ 黄金法则
如果您对API格式的决定有疑问，这些黄金规则可以帮助我们做出正确的决定。
- 扁平比嵌套好。
- 简单胜于复杂。
- 字符串比数字好。
- 一致性比定制更好。
就是这样——如果你已经走到了这一步，恭喜你！希望你学到了一些东西。
希望你度过美好的一天！
附录
🙏至此，非常感谢阅读🙏
