RESTful风格的接口

RESTful API

1、什么是RESTful API？

RESTful API通常根据 GET/POST/PUT/DELETE 来区分操作资源的动作，是一种风格，而不是一种约束和规约。

REST并没有一个明确的标准，更像是一种设计的风格，满足这种风格的程序接口称之为RESTful API

2、RESTful风格的主要特征

2.1 以资源为基础

资源可以是一个图片、音乐、HTML或JSON格式等网络上的一个实体，面向用户的一组数据等等...

2.2 统一接口

使用RESTful风格的接口，从接口上你可能只能定位其资源，但无法知晓它进行了什么操作，需要从GET/POST/PUT/DELETE等请求方法类型上进行判断。

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

2.3 URI指向资源

URI（统一资源标志符），用来标识抽象或物理资源的一个紧凑的字符串。RUI包括URL和URN，在更多时候可能代指RUL。RESTful是面向资源的，每种资源可能由一个或多个URI对应，但一个URI只指向一种资源。

2.4 无状态

服务器不能保存客户端的信息， 每一次从客户端发送的请求中，要包含所有必须的状态信息，会话信息由客户端保存， 服务器端根据这些状态信息来处理请求。

当客户端可以切换到一个新状态的时候发送请求信息， 当一个或者多个请求被发送之后, 客户端就处于一个状态变迁过程中。 每一个应用的状态描述可以被客户端用来初始化下一次的状态变迁。

3、RESTful API设计规范

3.1 URL设计规范

通常一个RESTful API的path组成如下：

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

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

此外，有时可能增删改查无法满足业务要求，可以在URL末尾加上action

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

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

• 1.不用大写字母，所有单词使用英文且小写

• 2.连字符用中杠"-"而不用下杠"_"

• 3.结尾不要包含正斜杠分隔符"/"

• 4.URL中不出现动词，用请求方式表示动作

• 5.资源表示用复数不要用单数

• 6.不要使用文件扩展名

  
  

3.2 HTTP动词

以下展示GET,POST,PUT,DELETE几种请求API的设计与含义分析。

在谈及GET,POST,PUT,DELETE的时候，就必须提一下接口的安全性和幂等性。

其中安全性是指方法不会修改资源状态，即读的为安全的，写的操作为非安全的。

而幂等性的意思是操作一次和操作多次的最终效果相同，客户端重复调用也只返回同一个结果。

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

HTTP Methods	安全性	幂等性	解释
GET	安全	幂等	读操作安全、不管查询一次，还是查询多次，结果都相同
POST	非安全	非幂等	写操作不安全、插入一次和插入多次，结果并不相同，数据量增多
PUT	非安全	幂等	写操作不安全、更新一次和更新多次，结果相同
DELETE	非安全	幂等	写操作不安全、删除一次和删除多次，结果相同

3.3 状态码和返回数据

服务器响应时，包含状态码和返回数据两个部分：

状态码

主要分为五大类：

• 1xx：相关信息
• 2xx：操作成功
• 3xx：重定向
• 4xx：客户端错误
• 5xx：服务器错误

主要常用状态码罗列在下面：

• 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的。
• 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
• 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）。
• 204 NO CONT202 Accepted - [*]：ENT - [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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

返回数据

针对不同操作，服务器向用户返回数据，而各个团队或公司封装的返回实体类也不同，但都返回JSON格式数据给客户端。

4、RESTful的缺点

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

比如RESTful API也有一些缺点：

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

如果业务需求和RESTful风格API不太匹配或者很麻烦，那也可以不用RESTful风格API。

无论那种风格的API都是为了方便团队开发、协商以及管理，不能墨守成规。