RESTful API URL 设计

RESTful 是目前最流行的 API 设计规范，也是各公司招聘面试的项目之一。很多人对 RESTful API 的设计还不是很规范，于是便有了本文。

URL 的设计，一般我们会采用：动词 + 宾语的形式表示。

RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /articles这个命令，GET是动词，/articles是宾语。

动词通常就是五种 HTTP 方法，对应 CRUD 操作。

• GET：读取（Read）
• POST：新建（Create）
• PUT：更新（Update）
• PATCH：更新（Update），通常是部分更新
• DELETE：删除（Delete）

根据 HTTP 规范，动词一律大写。

有些客户端只能使用GET和POST这两种方法。服务器必须接受POST模拟其他三个方法（PUT、PATCH、DELETE）。

这时，客户端发出的 HTTP 请求，要加上X-HTTP-Method-Override属性，告诉服务器应该使用哪一个动词，覆盖POST方法。

POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT

上面代码中，X-HTTP-Method-Override指定本次请求的方法是PUT，而不是POST。

在 SpringMVC 中会添加一个 HiddenHttpMethodFilter 过滤器。它会将表单上隐藏域_method属性改为put或者delete等再进行提交。因为只有form表单才具有post方法,而这个过滤器也只能将post方法转化,get则不行。不懂的可以看这篇文章：https://blog.csdn.net/jaryle/article/details/73656426。

宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词，不能是动词。比如，/articles这个 URL 就是正确的，而下面的 URL 不是名词，所以都是错误的。

• /getAllCars
• /createNewCar
• /deleteAllRedCars

既然 URL 是名词，那么应该使用复数，还是单数？

这没有统一的规定，但是常见的操作是读取一个集合，比如GET /articles（读取所有文章），这里明显应该是复数。

为了统一起见，建议都使用复数 URL，比如GET /articles/2要好于GET /article/2。

常见的情况是，资源需要多级分类，因此很容易写出多级的 URL，比如获取某个作者的某一类文章。

GET /authors/12/categories/2

这种 URL 不利于扩展，语义也不明确，往往要想一会，才能明白含义。

更好的做法是，除了第一级，其他级别都用查询字符串表达。

GET /authors/12?categories=2

下面是另一个例子，查询已发布的文章。你可能会设计成下面的 URL。

GET /articles/published

查询字符串的写法明显更好。

GET /articles?published=true

RESTful API 最好的例子就是 github 网站。大家经常使用，一定不陌生。所以可以借鉴 github 上的资源命名方式来开发自己的产品，设计自己的 RESTful API 和 URL。

： » RESTful API URL 设计