Restful API规范
一、简介
RESTful API 是应用程序接口 (API) 的一种架构风格，它使用 HTTP 请求来访问和使用数据。该数据可用于 GET、PUT、POST 和 DELETE 数据类型，这些数据类型是指有关资源的操作的读取、更新、创建和删除。
RESTful API（也称为 RESTful Web 服务或 REST API）基于表示状态传输 (REST)，它是一种架构风格和经常用于 Web 服务开发的通信方法。
二、设计原则。
- URL即资源，使用名词表示资源
- 接口应直观、简洁、风格命名保持一致
- 必须版本化，具有足够的灵活性来支持上层UI
三、RFC3986标准。
RFC3986标准，简单讲就是规定了如下：除了 数字 + 字母 + -_.~ 不会被转义，其他字符都会被以百分号（%）后跟两位十六进制数 %{hex} 的方式进行转义。
www 的 post form data 也就是 x-www-form-urlencode 的编码规则：除 -_.（没有 ~） 之外的所有 非字母、非数字 的字符都将被替换成 百分号（%）后跟两位十六进制数 %{hex}，空格（注意）则编码为加号 +。
RFC3986对 ~ 不做转码，x-www-form-urlencode 对 ~ 做转码 %7E。
RFC3986对 空格 转为 %20，x-www-form-urlencode 对 空格 转为 +。
JS的URL编码方式：encodeURIComponent。
// encodeURIComponent
console.log(encodeURIComponent("hello233 ~-_."))
hello233%20~-_.四、URI、URL和URN
URI（Uniform Resource Identifier ）：统一资源标识符，就是在某一规则下能把一个资源独一无二地标识出来。
URL（Uniform Resource Locator）：统一资源定位符。
URN（Uniform Resource Name）：统一资源名称。
URI可以分为URL,URN或同时具备locators 和names特性的一个东西。URN作用就好像一个人的名字，URL就像一个人的地址。换句话说：URN确定了东西的身份，URL提供了找到它的方式。
URL是URI的子集, 除了确定一个资源,还提供一种定位该资源的主要访问机制(如其网络“位置”)。例如： http://或 ftp://.。
当我们替代web地址的时候，URI和URL那个更准确？
URI更准确。
我们经常使用的URI不是严格技术意义上的URL。例如：你需要的文件在files.hp.com. 这是URI，但不是URL--系统可能会对很多协议和端口都做出正确的反应。http://files.hp.com 和ftp://files.hp.com可能得到完全不同的内容。这种情况可能更加普遍，想想不同谷歌域名上的不同服务啊。所以，用URI吧，这样你通常技术上是正确的，URL可不一定。
五、设计规范。
1.版本号
应该将API的版本号放入URL。 版本号以字符'v'开头，比如：v1
http://demo.com/cuc/sever/v12.路径(Endpoint)
接口路径，也称为端点(Endpoint)，代表一种资源的访问地址。
①使用名词表示资源，使用HTTP Method 描述操作
因为"资源"表示一种实体，所以应该是名词，URL不应该有动词，动词应该放在HTTP协议中，CRUD的操作不要体现在URL中。
反面教材：
查询员工 GET /v1/findEmployee?id=1000
新增员工 POST /v1/addEmployee
更新员工 POST /v1/updateEmployee?id=1000
删除员工 POST /v1/deleteEmployee?id=1000
正确实例：
查询员工 GET /v1/employee/1000
新增员工 POST /v1/employee
更新员工 PUT /v1/employee/1000
删除员工 DELETE /v1/employee/1000② 资源既可以是单个，也可以是一个集合，比如：user是单个资源，users是集合资源。 由于英文名词的复数规则众多，为了保持接口命名的一致性，我们建议URL里描述集合资源的名词统一使用单数。
反面示例：
查询单个员工 GET /v1/employees/1000
查询一组员工 GET /v1/employees正确示例：
查询单个员工 GET /v1/employee/1000
查询一组员工 GET /v1/employee3.使用小写字母，多个单词用"-"分隔，提高URL的可读性
RFC3986 定义了URI是大小写敏感的(除了scheme和host部分)，为了避免歧义，接口路径应尽量使用小写字母。
对于由多个单词构成的路径，推荐使用'-'(hyphen)分隔，避免使用驼峰命名（camelCase）、下划线命名(snake_case)、首字母大写的驼峰命名（PascalCase），以提高可读性。
例子：
camelCase : /v1/customer/1000/shippingAddress [Bad]
snake_case : /v1/customer/1000/shipping_address [Bad]
PascalCase : /v1/customer/1000/ShippingAddress [Bad]
hyphen : /v1/customer/1000/shipping-address [OK]
4.资源嵌套层次避免过深，尽量不超过2层
定义REST接口时，通常使用资源嵌套（多级路径）来标识资源之间的关系，资源嵌套层次尽量不超过2层，否则很难阅读和使用。
例子：
GET /v1/user/1000/company 查询ID等于1000的用户的公司信息
GET /v1/user/1000/company/10 查询ID等于1000的用户所属公司中ID=10的公司信息，嵌套两层
反面例子：
GET /v1/company/10/department/20302/employee/10830
GET /v1/zoo/1/area/3/animal/4
六. 筛选(Filtering)、排序(Sorting)、分页(Pagination)、字段选择
1.筛选（Filtering)
接口URL尽量保持简短，对于集合资源不同纬度的筛选，可通过组合不同的Query Param来实现。
反面案例：
GET /v1/externalEmployees
GET /v1/internalEmployees
GET /v1/internalAndSeniorEmployees
正确案例：
GET /v1/employee?state=internal&title=senior
2.排序(Sorting)
单个字段排序：
GET /v1/employee?sort=age&order=asc
GET /v1/employee?sort=age&order=desc多个字段排序：
字段名前缀,'+'：表示升序，'-'：降序，多个字段名以逗号分隔
GET /v1/employee?sort=+age,-userName3.分页(Pagination)
对于数据量比较大的集合资源，接口实现一定要支持分页。
常规分页有两个重要的参数：
- pageNo 获取那一页的记录，默认第一页。
- pageSize 每页返回多少条数据，推荐默认值25，必须限定此参数的最大值。
返回的资源列表为：[(pageNo-1)pageSize, pageNopageSize)
请求示例：
GET /v1/employee?pageNo=8&pageSize=20&sort=age&order=desc返回值可以采用以下数据格式：
{
"pageSize":20, // 页尺寸
"pageNo":8, // 页码
"totalCount":182, // 总记录数
"pageList":[
{
"id":13483,
"name":"Hehe",
"title":"senior"
},
{
"id":13484,
"name":"haha",
"title":"junior"
}
]
}
4.字段选择
调用方可能只需要资源的少量属性，接口提供方可支持客户端通过请求参数fields来选择返回的字段，多个字段以逗号分隔，示例如下：
GET /v1/employee?fields=id,name,age&pageNo=1&pageSize=20&sort=age&order=desc