API 面向资源设计

wastingAllTheseTears

已于 2022-08-29 11:22:09 修改

阅读量196

点赞数

文章标签：设计规范

于 2022-08-29 11:06:14 首次发布

原文链接：https://mp.weixin.qq.com/s/kLbu716qCrBfY-xSDJdJgQ

版权

首先介绍一些术语
任何API设计都遵循一种叫做“面向资源设计”的原则：
资源：资源是数据的一部分，例如：用户
集合：一组资源称为集合，例如：用户列表
URL：标识资源或集合的位置，例如：/user

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

例如，如果你想要获得订单列表。
不应该：

/systemOrders或/system_orders

应该：

/system-orders

2. 参数使用camelCase（驼峰形式）

例如，如果你想从一个特定的商店购买产品。
不应该：

/system-orders/{order_id}

或者

/system-orders/{OrderId}

应该：

/system-orders/{orderId}

3.指向集合的复数名称

如果你想获得系统的所有用户。
不应该：

GET /user

或：

GET /User

应该：

GET /users

4. 让动词远离你的资源URL

不要在URL中使用动词来表达你的意图。相反，使用适当的HTTP方法来描述操作。
不应该：

POST /updateuser/{userId}

或：

GET /getusers

应该：

PUT /user/{userId}

5. JSON属性使用camelCase驼峰形式

如果你正在构建一个请求体或响应体为JSON的系统，那么属性名应该使用驼峰大小写。
不应该：

{
   user_name: "Mohammad Faisal"
   user_id: "1"
}

应该：

{
   userName: "Mohammad Faisal"
   userId: "1"
}

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

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

product_order

应该：

product-orders

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

7. 使用API设计工具

有许多好的API设计工具用于编写好的文档，例如：
API蓝图：https://apiblueprint.org/
Swagger：https://swagger.io/
拥有良好而详细的文档可以为API使用者带来良好的用户体验。

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

始终对API使用版本控制，并将其向左移动，使其具有最大的作用域。版本号应该是v1，v2等等。
应该：
http://api.domain.com/v1/shops/3/products
始终在API中使用版本控制，因为如果API被外部实体使用，更改端点可能会破坏它们的功能。

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

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

{
  users: [ 
     ...
  ]
}

应该：

{
  users: [ 
     ...
  ],
  total: 34
}

10. 接受limit和offset参数

在GET操作中始终接受limit和offset参数。

应该：

GET /shops?offset=5&limit=5

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

11. 获取字段查询参

返回的数据量也应该考虑在内。添加一个fields参数，只公开API中必需的字段。

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

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

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

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

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

不应该：

GET /shops/123?token=some_kind_of_authenticaiton_token

相反，通过头部传递它们：

Authorization: Bearer xxxxxx, Extra yyyyy

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

13. 验证内容类型

服务器不应该假定内容类型。例如，如果你接受application/x-www-form-urlencoded，那么攻击者可以创建一个表单并触发一个简单的POST请求。
因此，始终验证内容类型，如果你想使用默认的内容类型，请使用：
content-type: application/json

14. 对CRUD函数使用HTTP方法

HTTP方法用于解释CRUD功能。
GET：检索资源的表示形式。
POST：创建新的资源和子资源。
PUT：更新现有资源。
PATCH：更新现有资源，它只更新提供的字段，而不更新其他字段。
DELETE：删除已存在的资源。

15. CORS（跨源资源共享）

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

16. 安全

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

17. 错误

当客户端向服务发出无效或不正确的请求，或向服务传递无效或不正确的数据，而服务拒绝该请求时，就会出现错误，或者更具体地说，出现服务错误。
例子包括无效的身份验证凭证、不正确的参数、未知的版本id等。
当由于一个或多个服务错误而拒绝客户端请求时，一定要返回4xx HTTP错误代码。
考虑处理所有属性，然后在单个响应中返回多个验证问题。