Restful API接口

REST（Representational State Transfer）。RESTful架构，就是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便。

访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，势必涉及到数据和状态的变化。
互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。

RESTful架构：

• 每一个URI代表一种资源；
• 客户端和服务器之间，传递这种资源的某种表现层；
• 客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

Restful API设计

非Rest设计，以往我们都会这么写：
http://localhost:8080/admin/getUser （查询用户）
http://localhost:8080/admin/addUser （新增用户）
http://localhost:8080/admin/updateUser （更新用户）
http://localhost:8080/admin/deleteUser （删除用户）
总结：以不同的URL（主要为使用动词）进行不同的操作。
Rest架构：
GET http://localhost:8080/admin/user （查询用户）
POST http://localhost:8080/admin/user （新增用户）
PUT http://localhost:8080/admin/user （更新用户）
DELETE http://localhost:8080/admin/user （删除用户）
总结：URL只指定资源，以HTTP方法动词进行不同的操作。用HTTP STATUS/CODE定义操作结果。
Restful：遵守了rest风格的web服务便可称为Restful。

一、协议

API与用户的通信协议，总是使用HTTPs协议。

二、域名

应该尽量将API部署在专用域名之下。

https://api.example.com

三、版本（Versioning）

应该将API的版本号放入URL。

https://api.example.com/v1/

四、路径（Endpoint）

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词（命名名词的时候，要使用小写、数字及下划线来区分多个单词）。
举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
https://api.example.com/v1/zoos https://api.example.com/v1/animals https://api.example.com/v1/employees

五、HTTP动词

【GET】 /users/1001 # 查看某个用户信息
【POST】 /users # 新建用户信息
【PUT】 /users/1001 # 更新用户信息(全部字段)
【PATCH】 /users/1001 # 更新用户信息(部分字段)
【DELETE】 /users/1001 # 删除用户信息
【PATCH】一般不用，用【PUT】
【HEAD】获取资源的元数据。
【OPTIONS】获取信息，关于资源的哪些属性是客户端可以改变的。

六、过滤信息

RESTful API 接口应该提供参数，过滤返回结果。
示例：【GET】 /{version}/{resources}/{resource_id}?offset=0&limit=20
?page=2&per_page=100：指定第几页，以及每页的记录数。

七、状态码

使用适合的状态码很重要，而不应该全部都返回状态码 200
状态码链接

• 200~299段 表示操作成功：
• 200（OK） 操作成功，正常返回
• 201（创建） 创建资源
• 202（已接受）202响应通常用于需要很长时间才能处理的操作。它表示该请求已被接受处理，但处理尚未完成。该请求可能会或可能不会最终被执行，甚至可能在处理时不允许。
• 300~399段 表示参数方面的异常
• 300 参数类型错误
• 301 参数格式错误
• 302 参数超出正常取值范围
• 303 token过期
• 304 token无效
• 400~499段 表示请求地址方面的异常：
• 400 找不到地址
• 404 NOT FOUND
• 500~599段 表示内部代码异常：
• 500 服务器代码异常
  服务器返回的数据格式，应该尽量使用JSON，避免使用XML。