REST API设计

关于REST API设计是一个很大的话题，虽然网上有很多文章介绍如何设计符合REST风格的API，但是大多只是简单介绍REST API设计的一些基本原则，例举了一些非常简单的例子。但是在真实开发场景中，业务场景可能会千变万化，非常复杂，一些基本的REST设计原则很难简单到应用的我们的API设计中。

这篇博客会介绍一些基本的REST API设计的知识点和注意事项，以后也会不断更新增加自己新的理解和业界的一些最佳实践。

1. 在URL中，如果要包含多个单词组成的资源名称，单词之间使用中划线，不要使用驼峰和下划线。

2. 对于资源的名称，尽量使用复数形式。比如以博客系统或者购物车系统举例子。其实资源名称不管是使用单数还是复数，都是不完美的。因为如果是复数，GET /articles表示获取所有文章，没问题。但是POST /articles，表示的应该是创建单个文章，这时使用复数形式就不合适了。但是为了统一，我们看到很多文章都推荐使用复数形式。如果你看到某些网站使用单数形式（不管是get还是post），也不用奇怪，这个不是绝对的。

获取所有博客文章
GET /articles
创建一个新的文章
POST /articles
更新一个文章
PUT /articles/{article-id}
为文章创建（新增）一个新的评论
POST /articles/{article-id}/comments/

往购物车中增加一个新的商品条目
POST /carts/{cart-id}/items

3. POST表示新增。但是如果新增的资源不是在根目录下（“/”），而是创建在某个资源的下一层级目录下，这时候除了表示新增的概念，还有“往上层资源添加”的语意，比如上边给的例子中往文章中添加评论、往购物车中添加商品条目。他们表示的语意不仅仅是简单的“新增”。

4. REST风格的API核心特征之一是在URI中使用资源名称和资源标志符，而不使用动词，但这不是绝对的。有些业务场景不能简单的转化成对资源的CRUD，比如页面上有一个“发送邮件”按钮，或者购物网站购物车页面的“结账”按钮，点这些按钮发出的操作，显然不能简单的匹配到对某个资源的CRUD操作，这时我们可以灵活操作。基本的原则是这些不能严格匹配上REST基本的增删改查操作，可以使用POST操作。也就是说POST除了用于新增，还可以用于其他不属于增删改查范畴的任何操作。

5. 在使用PUT去更新资源时，即使是只是更新了资源的个别属性，也需要将资源的所有属性都携带。因为HTTP相关RFC规定PUT这个Verb的语意就是资源如果不存在，创建新的，如果已经存在，则更新。所以PUT必须是幂等性的（GET，POST，DELETE，PUT，PATCH只有POST和PATCH不是幂等性的）。

6.如果需要只更新资源某一个属性，可以在单独设计一个URI，比如一个博客系统需要修改某篇文章的标题，可以将API设计成：

/articles/{id}/title

在PUT请求的body里边，将内容设置成要设置的标题内容。

这对于很多前端框架来说可以非常容易的来实现，只需要一条语句就可以实现，比如：

//伪代码
axios.put(`/api/v1/articles/10`, title)

 虽然有的文章推荐REST风格的API除了文件传送请求体使用form表单格式，其他场景下一律使用JSON格式（XML也不推荐），但是规矩是死的，针对特定情况还是特殊处理。

7. 在URI里边，资源节点最好不要超过三层，比如下边给出了例子， 有两层，一个是articles, 一个是comments。如果层数太多，可读性也会变差。

DELETE /articles/{article-id}/comments/{comment-id}

8. 在设计REST API时，我们需要提前考虑好我们整个系统会有哪些资源以及这些资源的层级关系以及他们的交互关系。为了更好的设计API，可以参考知名网站的API参考，因为很多知名网站都给开发者提供了他们提供的API Reference，可以拿来参考。（你可以搜索API Reference，便可以轻易获取一堆相关连接）

9. 在URI里边，也不一定是使用资源ID来标志一个资源，为了增强可读性，有的网站就使用了资源名称来代替资源ID来唯一的标志一个资源。比如AWS针对管理lambda（function）资源提供的API，就使用“function name”作为资源唯一标志符。

PUT /2017-10-31/functions/FunctionName/concurrency HTTP/1.1
Content-type: application/json

{
   "ReservedConcurrentExecutions": number
}


FunctionName
The name of the Lambda function.

Name formats

Function name - my-function.

Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.

Partial ARN - 123456789012:function:my-function.

持续更新中...

参考资料：

Tutorial | Building REST services with Spring

REST API Best Practices – REST Endpoint Design Examples

https://github.com/RestCheatSheet/api-cheat-sheet

Introduction to Graph APIs - The Zapier Engineering Blog | Zapier

REST / HTTP methods: POST vs. PUT vs. PATCH

REST: Partial updates with PATCH

Best practices for REST API design - Stack Overflow Blog

Best practices for REST API security: Authentication and authorization - Stack Overflow Blog

PutFunctionConcurrency - AWS Lambda

(101条消息) 优秀REST风格 API的设计原则_逍遥子_的博客-CSDN博客_rest风格接口实例