RestfulAPI规范

Restful是目前最流行的API设计规范，用于Web数据接口的设计。

1. 动词+宾语

   • Restful的核心思想就是，客户端发出的数据操作指令都是“动词+宾语”的结构。

   • 如：GET/articles这个接口，GET是动词，articles是宾语

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

     • GET：读取（read）
     • POST：新建（create）
     • PUT：更新（update）
     • PATCH：更新（update）通常是部分更新
     • DELETE：删除（delete）

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

2. 动词的覆盖

   • 有些客户端只能使用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。

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

3. 宾语必须是名词

   • 宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词，不能是动词。

   • 比如，/articles这个 URL 就是正确的，而下面的 URL 不是名词，所以都是错误的。

     /getAllCars
     /createNewCar
     /deleteAllRedCars

4. 复数 URL

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

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

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

5. 避免多级 URL

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

     GET /authors/12/categories/2
     - 这种 URL 不利于扩展，语义也不明确，往往要想一会，才能明白含义。

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

     GET /authors/12?categories=2

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

     GET /articles/published

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

     GET /articles?published=true