rest api设计

rest api设计

CRUD简介

基于 CRUD 的 API 是指提供包含实例的资源集合的 API，效仿 create、read、update 和 delete 生命周期模式。当有一组代表内容或状态的资源实例时，CRUD 模式很有用，它通常遵循以下模式：

• GET /articles – 列出/分页/过滤文章列表
• POST /articles – 创建新文章
• GET /articles/{articleId} – 获取文章详情
• PATCH /articles/{articleId} – 更新文章详情
• DELETE /articles/{articleId} – 删除指定ID的文章

 一个严重的误解是 REST 的 API 必须是基于 CRUD 的，这两者之间没有任何的联系，都只是API设计风格的一种方式而已。

在讨论 CRUD 之外的API风格之前，需要澄清一个关于 REST 的严重误解：

CRUD 并不是对 RESTful API 的要求。

事实上，在 Fielding’s dissertation 的论文中并没有提及 CRUD 。

在谈到基于 REST 的 API 时，很多人将利用基于 CRUD 风格的资源与 REST 风格混淆一起。

REST 是规范客户端和服务端之间通讯的方式，利用 HTTP 协议提供的功能，这些限制可以自由地专注于 API 设计：

1. 统一的接口：来自不同客户端的请求都是一样的，无论客户端是浏览器、移动设备还是其他任何设备
2. 客户端-服务端分离 ：客户端和服务端独立运行，它们之间的交互仅以请求和响应的形式进行
3. 无状态 ：服务端不存储使用 API 的用户的任何信息，因此客户端必须在每次请求时提供处理请求的所有必要信息
4. 分层系统：客户端不知道在客户端和响应请求的实际服务器之间有多少层，这是 HTTP 的一个关键原则，允许缓存服务器、反向代理和访问安全分层——所有这些对发送请求的客户端都是透明的
5. 可缓存 ： 服务端响应必须包含有关数据是否可缓存的信息，允许客户端或代理在 API 服务器之外缓存数据
6. 按需代码（可选）：能够根据请求将可执行代码从服务器发送到客户端，从而扩展客户端功能。

 同样，REST 不需要具有基于 CRUD 风格的资源。CRUD 是一种我们可以应用于 REST 的 API 风格，但它不是构成基于 REST API 的必要条件。

这在设计 API 时可以更加的自由，这样可以在适当的时候提供具有基于 CRUD 风格的资源，而在不需要CRUD的时候混合使用功能性资源。

在设计 API 时，不必局限于这种风格，可以探索一些其他扩展风格，可以帮助设计出满足当前和未来开发需求的出色的API风格。