什么是 RESTFul API
REST 的全称是 Representational State Transfer——表象层状态转变
- 每一个 URL 代表一种资源
- 客户端和服务器之间，传递资源的某种表现层
- 客户端通过 http 请求类型（get, post, put, delete 等），对服务器资源进行操作
RESTFul API 六大原则
-
C-S 架构
Client-Server 架构，数据的存储在 Server 端，Client 端只需使用就行。
-
无状态
客户端的每一次请求带有充分的信息能够让服务端识别，服务端能够根据请求的各种参数，无需保存客户端的状态，将响应正确返回给客户端。
-
统一接口
REST 接口约束定义为：
- 资源识别
- 请求动作
- 响应信息
它表示通过uri 标出你要操作的资源，通过请求动作（http method）标识要执行的操作，通过返回的状态码来表示这次请求的执行结果。
-
一致的数据格式
服务端返回 XML 或者 JSON 格式数据。
-
可缓存
客户端可以缓存页面的响应内容。
-
按需编码、可定制代码
服务端可选择临时给客户端下发一些功能代码让客户端来执行，从而定制和扩展客户端的某些功能。
RESTFul API 最佳示例
-
版本控制
在 url 后面加上 v1, v2, v3 表示版本号
http://example.com/api/v2 -
参数命名规范
query parameter 可以采用驼峰命名法，也可以采用下划线命名的方式。
http://example.com/api/users/today_login //获取今天登陆的用户 http://example.com/api/users/today_login&sort=login_desc //获取今天登陆的用户、登陆时间降序排列 -
url 命名规范
在 RESTFul 架构中，每个 url 代表一种资源，所以 url 中不能有动词，只能有名词，并且名词中也应该使用复数。实现者应使用相应的 Http 动词 GET、POST、PUT、PATCH、DELETE、HEAD 来操作这些资源即可。
不规范的 url：
http://example.com/api/getAllUsers //GET 获取所有用户 http://example.com/api/getUser/1 //GET 获取 id 为 1 用户信息 http://example.com/api/updateUser/1 //POST 更新标识为 1 用户信息规范的 RESTFul 风格的 url：
http://example.com/api/users //GET 获取所有用户信息 http://example.com/api/users/1 //GET 获取 id 为 1 用户信息 http://example.com/api/users //POST 添加新的用户 http://example.com/api/users/1 //PUT 更新 id 为 1 用户信息 http://example.com/api/users/1 //DELETE 删除 id 为 1 用户信息 -
统一返回数据格式
对于合法的请求应该返回统一的数据格式。
- code——包含一个整数类型的 HTTP 响应状态码。
- status——包含文本：”success”，”fail” 或 ”error”。HTTP 状态响应码在 500 - 599 之间为 ”fail”，在 400 - 499 之间为 ”error”，其它均为 ”success”（例如：响应状态码为 1XX、2XX 和 3XX）。这个根据实际情况其实是可要可不要的。
- message——当状态值为 ”fail” 和 ”error” 时有效，用于显示错误信息。参照国际化（il8n）标准，它可以包含信息号或者编码，可以只包含其中一个，或者同时包含并用分隔符隔开。
- data——包含响应数据。当状态值为 ”fail” 或 ”error” 时，data 仅包含错误原因或异常名称、或者 null 也是可以的。
例如，返回成功响应的 JSON 格式数据：
{ "code": 200, "message": "success", "data": { "userName": "zhangsan", "age": 18, "address": "shanghai" } }返回失败的响应 JSON 格式：
{ "code": 401, "message": "error message", "data": null } -
合理使用 query parameter
在请求数据时，客户端经常会对数据进行过滤和分页等要求，而这些参数推荐采用 HTTP Query Parameter 的方式实现。
//获取第一页且关键词包含王的用户 http://example.com/api/users?page=1&key=王
HTTP 状态码
- 总体分类
- 1xx：指示信息——表示请求已接收，继续处理
- 2xx：成功——表示请求已经被成功接收并处理
- 3xx：重定向——完成请求需要进一步处理（跳转）
- 4xx：客户端错误——请求有错误或者请求无法实现
- 5xx：服务器端错误——服务器端未能实现合法请求
- 常见 http 状态码
- 200 OK：正常返回信息（请求被成功处理）
- 301 Permanently Moved：永久重定向
- 302 Temporarily Moved：临时重定向
- 400 Bad Request：客户端请求有错误
- 401 Unauthorized：请求未授权
- 403 Forbidden：服务器收到请求，但拒绝提供服务
- 404 Not Found：请求资源不存在
- 500 Internal Server Error：服务器内部错误
- 503 Server Unavailable：服务器当前无法处理请求，一段时间后可能恢复
