RESTful产生背景
网络应用程序 分为前端和后端两个部分
当前端设备层出不穷 手机 平板 桌面电脑 其 专用设备
必须有一种统一的机制 方便不同的前端设备与后端进行通信
这导致API构架的流行 甚至出现"API First"的设计思想
RESTful API是目前比较成熟的一套互联网应用程序的API设计理论

如何设计一套合理 好用的API

RESTful API
一 协议
API与用户的通信协议 总是使用HTTPs协议

二 域名
应该尽量将API部署在专用域名之下 https://api.example.com
如果确定API很简单 不会有进一步扩展 可以考虑放在主域名下 https://example.org/api/

三 版本 Versioning
应该将API的版本号放入URL https://api.example.com/v1/
另一种做法是 将版本号放在HTTP头信息中 但不如放入URL方便和直观 Github采用这种做法

四 路径 Endpoint
路径又称"终点" endpoint  表示API的具体网址

在RESTful架构中 每个网址代表一种资源 resource  所以网址中不能有动词 只能有名词 而且所用的名词往往与数据库的表格名对应 一般来说 数据库中的表都是同种记录的"集合" collection  所以API中的名词也应该使用复数

举例来说 有个API提供动物园 zoo 的信息 还包括各种动物和雇员的信息 则它的路径应该设计成下面这样

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

五 HTTP动词

对于资源的具体操作类型 由HTTP动词表示

常用的HTTP动词有下面五个 括号里是对应的SQL命令  

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

还有两个不常用的HTTP动词

HEAD：获取资源的元数据
OPTIONS：获取信息 关于资源的哪些属性是客户端可以改变的

下面是一些例子

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

六 过滤信息 Filtering

如果记录数量很多 服务器不可能都将它们返回给用户 API应该提供参数 过滤返回结果

下面是一些常见的参数

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

参数的设计允许存在冗余 即允许API路径和URL参数偶尔有重复 如 GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的
七 状态码 Status Codes

服务器向用户返回的状态码和提示信息 常见的有以下一些 方括号中是该状态码对应的HTTP动词  

200 OK - [GET]：服务器成功返回用户请求的数据 该操作是幂等的 Idempotent  
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功
202 Accepted - [*]：表示个请求已经进入后台排队 异步任务
204 NO CONTENT - [DELETE]：用户删除数据成功
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误 服务器没有进行新建或修改数据的操作 该操作是幂等的
401 Unauthorized - [*]：表示用户没有权限 令牌 用户名 密码错误  
403 Forbidden - [*] 表示用户得到授权 与401错误相对  但是访问是被禁止的
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录 服务器没有进行操作 该操作是幂等的
406 Not Acceptable - [GET]：用户请求的格式不可得 如用户请求JSON格式 但是只有XML格式  
410 Gone -[GET]：用户请求的资源被永久删除 且不会再得到的
422 Unprocesable entity - [POST/PUT/PATCH] 当创建个对象时 发生个验证错误
500 INTERNAL SERVER ERROR - [*]：服务器发生错误 用户将无法判断发出的请求是否成功

状态码的完全列表参见这里
八 错误处理 Error handling

如果状态码是4xx 就应该向用户返回出错信息 一般来说 返回的信息中将error作为键名 出错信息作为键值即可 {
error: "Invalid API key"
}

九 返回结果
针对不同操作 服务器向用户返回的结果应该符合以下规范
GET /collection：返回资源对象的列表 数组
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回个空文档

十 Hypermedia API
RESTful API最好做到Hypermedia 即返回结果中提供链接 连向其 API方法 使得用户不查文档 也知道下一步应该做什么
如 当用户向api.example.com的根目录发出请求 会得到这样个文档
{"link": {
"rel":   "collection https://www.example.com/zoos",
"href":  "https://api.example.com/zoos",
"title": "List of zoos",
"type":  "application/vnd.yourformat+json"
}}
文档中有个link属性 用户读取这个属性就知道下一步该调用什么API了 rel表示这个API与当前网址的关系 collection关系 并给出该collection的网址  href表示API的路径 title表示API的标题 type表示返回类型
Hypermedia API的设计被称为HATEOAS Github的API就是这种设计 访问api.github.com会得到个所有可用API的网址列表
{"current_user_url": "https://api.github.com/user","authorizations_url": "https://api.github.com/authorizations",// ...
}
如果想获取当前用户的信息 应该去访问api.github.com/user 然后就得到了下面结果
{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3"
}

上面代码表示 服务器给出了提示信息 以及文档的网址

十一 其
 1 API的身份认证应该使用OAuth 2.0框架
 2 服务器返回的数据格式 应该尽量使用JSON 避免使用XML
/


RESTful绝大部分内容是关于API设计时规范推荐的做法 并没有新东西
只要符合REST设计原则的API都可以被称为RESTful

RESTful的核心就是后端将资源发布为URI
前端通过URI访问资源 并通过HTTP动词表示要对资源进行的操作

资源:后端提供的所有内容都可以被定义为资源

典型的RESTful如下
GET       /student     //查找所有学生
GET       /student/1  //查找id为1的学生
POST     /student     //新增个学生
PUT     /student/1     //修改id为1的学生
DELETE  /student/1  //删除id为1的学生

为什么用RESTful
前后端分离 以API为界限进行解耦 会产生大量的API 采用RESTful来设计API 好处



1 表现力更强 更易于理解
2 RESRful是无状态 所以不管前端是何种设备何种状态都可以无差别的请求资源

怎么用RESTful
1 每个资源使用2个URL 网址中只能有名词
2 对于资源的操作类型由HTTP动词来表示
3 统一的返回结果
4 返回正确的状态码
5 允许通过HTTP内容协商 建议格式预定义为JSON
6 对可选发杂的参数 使用查询字符串 ？
7 返回有用的错误信息(message)
8 非资源请求用动词 这看起似乎和1中的说法有矛盾 但这里指的是非资源 而不是资源



REST的使用场景是Machine-to-machine的系统集成 目标是让服务发布者和消费者在最小约束下自由演化
简单讲就是服务输入输出的语义
消费者只需知道服务的根资源的URI 就可以由根资源引导到所需的资源

换句话说 消费者和发布者的耦合只在于根资源的URI以及各资源及其操作的语义

透明性 暴露资源存在

充分利用 HTTP 协议本身语义
无状态 这点非常重要
在调用个接口 访问 操作资源 的时候
可以不用考虑上下文 不用考虑当前状态 极大的降低了复杂度HTTP 本身提供了丰富的内容协商手段 无论是缓存
还是资源修改的乐观并发控制 都可以以业务无关的中间件来实现





1. 轻量 直接基于http 不在需要任何别的诸如消息协议 get/post/put/delete为CRUD操作
2. 面向资源 一目了然 具有自解释性
3. 数据描述简单 一般以xml json做数据交换


个文件操作接口 传统模式：

api/getfile.php - 获取文件信息 下载文件
api/uploadfile.php - 上传创建文件
api/deletefile.php - 删除文件

RESTful：

api/file 只需要这个接口
GET 方式请求 api/file - 获取文件信息 下载文件
POST 方式请求 api/file - 上传创建文件
DELETE 方式请求 api/file - 删除某个文件




RESTFUL中的方法：GET POST PUT PATCH DELETE OPTIONS HEAD TRACE


目前互联网公司的应用架构基本 是前后端分离 后端的接口 采用restful架构

restful架构最主要的是遵循rest的思想统一资源接口

REST全称：Representational State Transfer 翻译成中文就是“表述性状态转移” 表述的对象就是资源 在web的rertful架构中都是通过uri来一一对应资源
如/api/person/1 URI既可以看成是资源的地址 也可以看成是资源的名称 代表的就是唯一的资源 但是不能表示对资源的操作 操作是结合标准的http方法 get post put等 来实现的

restful的http方法 GET HEAD POST PUT DELETE OPTIONS TRACE PATCH
根据RFC2616第九章说明 http方法的定义有两点：safe and Idempotent 即安全性和幂等性
可以结合这两点对以上方法进行说明

1 GET
安全 幂等 用于获取资源
2 HEAD
安全 幂等 与get方法类似 但不返回message body内容 仅仅是获得获取资源的部分信息 content-type content-length  restful框架中较少使用

3 POST
非安全 非幂等 用于创建子资源

4 PUT
非安全 幂等 用于创建 更新资源

5 DELETE非安全 幂等 删除资源

6 OPTIONS安全 幂等 用于url验证 验证接口服务是否正常

7 TEACE
安全 幂等 维基百科“回显服务器收到的请求 这样客户端可以看到 如果有 哪一些改变或添加已经被中间服务器实现 ”
restful框架中较少使用

8 PATCH
非安全 幂等
用于创建 更新资源 于PUT类似 区别在于PATCH代表部分更新
后来提出的接口方法 使用时可能去要验证客户端和服务端是否支持

1 post和put的区别
post和put的区别在于uri 或说
post用于创建子资源
如接口 POST /api/person/创建个资源
/api/person/1或/api/person/2
或/api/person/n 创建了新的uri

而put方法创建资源的uri是 PUT /api/person/1 这样就创建了个资源 如果1已经存在那么就是更新 所以put并不 只是更新操作
再有post是非幂等的
通常情况下 都会将post get put delete对应到CRUD操作上 但实际上put并不是只能更新

2 patch的使用：
patch是2010后成为的正式http方法 详见RFC5789 它是对put的补充 在没有patch之前 都是用put进行更新操作 这时候接口中通常会有个逻辑规则 如：如果对象的的个字符属性为NULL 那么就是不更新该属性 字段 值 如果对象的字符属性是“” 那么就更新该属性 字段 的值 通过这种方式来避免全部覆盖的操作 现在有了patch就解决了这种判断 在put接口中不管属性是不是null 都进行更新 在patch接口中就对非null的进行更新

3 uri的使用问题
uri即使代表资源的 通过不同的方法来区分操作 那么像如下的接口就已经违反了restful规范：
GET /api/getPerson/1
DELETE /api/delPerson/1
GET /api/person/get/1
DELETE /api/person/delete/1

在复合规范的前提下 uri的定义应该也是实际使用中应该考虑的 如uri包涵那些信息？如版本 资源分类 资源名称 表述格式等 对于设计上的不多说了 直接看下面的url：
/api/1.0/person/man/1.xml
/api/2.0/person/man/1.json

这样的url很常见也很直观 对不同版本接口增加了版本信息 并且对数据的表述格式进行了显式指定 不是不好 但是按照“统一资源接口”的思想 资源的uri已经不唯一了
有说对于版本号 表述形式等可以放到http的accept中进行指定


4 查询问题的讨论：
按照rest建议 查询操作要使用get方法 但是实际情况中处理起来比较麻烦 如：报表统计查询 需要传递的参数很多 就SpingMVC来说 如果采用get方法 那么@RequestParam接收的参数非常多 接口很难看 通常会封装为java对象 希望通过@RqeustBody接收并处理 但这是不支持get方法 所以很蛋疼
对于这种情况 最简单的方式就是改成post方式 而且很多公司都是这么干的 但又觉得违反了restful规范 不改成post方式的话可能就需要将传递的参数对象细腻转为json串 后端字符串接收后再转为对象 这样感觉耶不太好 url中显式输出参数信息 个别情况json串太长活着包含特殊字符等也都很麻烦


火狐浏览器上的resteasy插件来进行测试