Restful API 设计规范

简介

REST（英文：Representational State Transfer，简称REST，直译过来表现层状态转换）是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。Rest是一种轻量级,跨平台,跨语言的架构设计，它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。 Rest（Representational State Transfer）决定了接口的形式与规则。

Restful是基于http方法的API设计风格，而不是一种新的技术。Restful对接口开发提供了一种可以广泛适用的规范，减少了前端后端交互接口交流的口舌成本，是约定大于配置的体现。通过Restful可以很容易知道：

• 看Url就知道要什么资源
• 看http method就知道针对资源干什么
• 看http status code就知道结果如何

URL设计规范

URL是统一资源定位器 ,通常一个完整的URL组成由以下几个部分构成：

scheme "://" host  ":"  port "/" path [ "?" query ][ "#" fragment ]

其中：

• scheme: 指底层用的协议，如http、https、ftp
• host: 服务器的IP地址或者域名
• port: 端口，http默认为80端口
• path: 访问资源的路径，就是各种web 框架中定义的route路由
• query: 查询字符串，为发送给服务器的参数，在这里更多发送数据分页、排序等参数。
• fragment: 锚点，定位到页面的资源

在设计API时URL的path是需要认真考虑的，而RESTful对path的设计做了一些规范，通常一个RESTful API的path组成如下：

/{version}/{resources}/{resource_id}

其中：

• version：API版本号，有些版本号放置在头信息中也可以，通过控制版本号有利于应用迭代。
• resources：资源，RESTful API推荐用小写英文单词的复数形式。
• resource_id：资源的id，访问或操作该资源。

当然，有时候可能资源级别较大，其下还可细分很多子资源也可以灵活设计URL的path，例如：

/{version}/{resources}/{resource_id}/{subresources}/{subresource_id} 此外，有时可能增删改查无法满足业务要求，可以在URL末尾加上action，例如：

/{version}/{resources}/{resource_id}/action

其中action就是对资源的操作。

RESTful API的URL具体设计的规范如下：

• 不用大写字母，所有单词使用英文且小写
• 连字符用中杠"-“来提高URI的可读性，而不用下杠”_"
• 正确使用 "/"表示层级关系，URL的层级不要过深，并且越靠前的层级应该相对越稳定
• 结尾不要包含正斜杠分隔符"/"
• URL中不出现动词，用请求方式表示动作
• 资源表示用复数不要用单数
• 不要使用文件扩展名

版本

应该将API的版本号放入URL中，不要发布无版本的API，比如：

https://api.hcshow.com/v1/

面向扩展开放，面向修改关闭：也就是说一个版本的接口开发完成测试上线之后，我们一般不会对接口进行修改，如果有新的需求就开发新的接口进行功能扩展。这样做的目的是：当你的新接口上线后，不会影响使用老接口的用户。如果新接口目的是替换老接口，也不要在v1版本原接口上修改，而是开发v2版本接口，并声明v1接口废弃！

路径

在RESTful架构中，每个网址代表一种资源（resource），所有网址请求接口中不能有动词，只能有名词，这些名词往往与数据库的表格名对应，应该使用复数。示例：

https://api.hcshow.com/v1/users
https://api.hcshow.com/v2/articles

HTTP动词

对于资源的具体操作类型，由HTTP动词表示。常用的HTTP动词有下面五个（括号里是对应的SQL命令）:

• GET（SELECT）：从服务器获取资源（一项或多项），例：GET /users（获取所有用户）
• POST（CREATE）：在服务器新建一个新的资源，例：POST /users（创建用户）
• PUT（UPDATE）：在服务器更新资源（客户端提供更新后的完整资源），例：PUT /users/12（更新编号为 12 的用户）
• PATCH（UPDATE）：在服务器更新资源（客户端提供更新的属性，可以看作是部分更新，使用较少），例：
• DELETE（DELETE）：从服务器删除资源，例：DELETE /users/12（删除编号为 12 的用户）

示例：

GET    /users：列出所有的用户（列表信息）
GET    /users/ID：获取某个指定的单个用户的信息
POST   /users：创建一个新用户
PUT    /users/ID：更新某个指定用户的信息（提供该用户的全部信息）
PATCH  /users/ID：更新某个指定用户的信息（提供该用户的部分信息）
DELETE /users/ID：删除某个用户

## 复杂资源关系的表达 
GET    /depts/ID/users：列出某个指定部门的所有用户
DELETE /depts/ID/users/ID：删除某个指定部门的指定用户
GET /cars/711/drivers    返回使用过编号711汽车的所有司机
GET /cars/711/drivers/4 返回使用过编号711汽车的4号司机

在谈及GET,POST,PUT,DELETE的时候，就必须提一下接口的安全性和幂等性，其中安全性是指方法不会修改资源状态，即读的为安全的，写的操作为非安全的。而幂等性的意思是操作一次和操作多次的最终效果相同，客户端重复调用也只返回同一个结果。

上述四个HTTP请求方法的安全性和幂等性如下：

过滤信息（Filtering）

如果记录数量很多，服务器不应该都将它们全部返回给用户。此时API应该提供参数，过滤返回结果，比如：

users?limit=10：指定返回记录的数量
users?offset=10：指定返回记录的开始位置。
users?pageNum=2&pageSize=100：指定第几页，以及每页的记录数。
users?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
users?animal_type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /depts/ID/users与 GET /users?depts_id=ID 的含义是相同的。

返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。比如：

• GET /collection：返回资源对象的列表（数组）
• GET /collection/resource：返回单个资源对象
• POST /collection：返回新生成的资源对象
• PUT /collection/resource：返回完整的资源对象
• PATCH /collection/resource：返回完整的资源对象
• DELETE /collection/resource：返回一个空文档

示例

• 获取所有用户 HTTP GET http://api.hcshow.com/user-management/managed-users
• 创建新用户 HTTP POST http://api.hcshow.com/user-management/managed-users
• 根据给定id获取用户 HTTP GET http://api.hcshow.com/user-management/managed-users/{id}
• 根据给定id更新用户 HTTP PUT http://api.hcshow.com/user-management/managed-users/{id}
• 根据给定id删除用户 HTTP DELETE http://api.hcshow.com/user-management/managed-users/{id}
• 根据某些特定资源属性对资源排序，过滤或限制 http://api.hcshow.com/user-management/managed-users http://api.hcshow.com/user-management/managed-users?region=USA http://api.hcshow.com/user-management/managed-users?region=USA&brand=XYZ http://api.hcshow.com/user-management/managed-users?region=USA&brand=XYZ&sort=installation-date

小结

RESTful风格的API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为REST是一种风格，而不是一种约束或规则，过于理想的RESTful API 会付出太多的成本。RESTful API也有一些缺点，比如：

• 比如操作方式繁琐，RESTful API通常根据GET、POST、PUT、DELETE 来区分操作资源的动作，而HTTP Method 本身不可直接见，是隐藏的，而如果将动作放到URL的path上反而清晰可见，更利于团队的理解和交流。
• 有些浏览器对GET,POST之外的请求支持不太友好，还需要特殊额外的处理。
• 过分强调资源，而实际业务API可能有各种需求比较复杂，单单使用资源的增删改查可能并不能有效满足使用需求，强行使用RESTful风格API只会增加开发难度和成本。

所以，当你或你们的技术团队在设计API的时候，如果使用场景和REST风格很匹配，那么你们可以采用RESTful 风格API。但是如果业务需求和RESTful风格API不太匹配或者很麻烦，那也可以不用RESTful风格API或者可以借鉴一下，毕竟无论那种风格的API都是为了方便团队开发、协商以及管理，不能墨守成规。