使用Restful API设计更加规范的数据接口

什么是Restful API

REST是设计风格而不是标准。是指客户端和服务器的交互形式。核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。

Restful API有几个特性：

面向资源：接口命名都是zoos、animals，而不是getAllAnimals这样的
使用Http动词：GET/PUT/POST/DELETE/PATCH/HEAD/OPTIONS，而不是我们日常只用的GET和POST

设计原则

1、在接口命名时应该用名词，不应该用动词，因为通过接口操作到是资源。
2、在url中加入版本号，利于版本迭代管理更加直观
https://www.rgc.com/v1/
3、对于资源的操作类型应该是通过http动词表示。

• GET /zoos：列出所有动物园
• POST /zoos：新建一个动物园
• GET /zoos/ID：获取某个指定动物园的信息
• PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
• DELETE /zoos/ID：删除某个动物园
• GET /zoos/ID/animals：列出某个指定动物园的所有动物
• DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

4、HTTP Method分别对于资源的CURD操作

• GET（SELECT）：从服务器取出资源（一项或多项）。
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
• DELETE（DELETE）：从服务器删除资源。

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

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

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

6、 避免多级 URL

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

GET /authors/12/categories/2

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

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

GET /authors/12?categories=2

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

GET /articles/published

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

GET /articles?published=true

issues

1、如果是对一条记录有多种动作怎么做呢？
这里有两种方式：

• 第一种

POST /datas/1?action=reportError
POST /datas/1?action=mark
POST /datas/1?action=assign

• 第二种

POST /datas/1/reportError
POST /datas/1/mark
POST /datas/1/assign

以上两种方式很明显第二种会更好一点

2、client验证用户名或者电话是否存在，该如何设计？
可以设计成这样
GET /users/{userName}?action=check ,对userName进行check操作

参考阅读

http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html