简介
REST(Representational State Transfer): 表象层状态转变
RESTful 对 API 进行规范和约束, 使得 API 统一规范, 增强 API 的可读性, 便于开发.
设计原则
1, 每一个 URI 代表一种资源
2, 客户端通过四个 HTTP 动词(get,post,put,delete), 对服务器端资源进行操作
因此, 这种风格的接口 url 中没有动词, 而是通过四个 HTTP 动词 (get,post,put,delete) 来代表动作.
Http 动词
分别对应四种基本操作:
GET 用来获取资源
POST 用来新建资源(也可以用于更新资源)
PUT 用来更新资源
DELETE 用来删除资源
具体实施
版本控制
如 GitHub 开放平台的 API: http://developer.github.com/v3/ http://developer.github.com/v3/ http://developer.github.com/v3/ 可以发现, 一般的项目加版本 v1,v2,v3 版本号, 为的是兼容一些老版本的接口, 这个加版本估计只有大公司大项目才会去使用.
参数命名规范
query parameter 可以采用驼峰命名法, 也可以采用下划线命名的方式, 推荐采用下划线命名的方式, 据说后者比前者的识别度要高, 其中, 做前端开发基本都后后者, 而做服务器接口开发基本用前者.
http://example.com/api/users/today_login 获取今天登陆的用户
http://example.com/api/users/today_login&sort=login_desc 获取今天登陆的用户, 登陆时间降序排列
url 命名规范
API 命名应该采用约定俗成的方式, 保持简洁明了. 在 RESTful 架构中, 每个 url 代表一种资源, 所以 url 中不能有动词, 只能有名词, 并且名词中也应该使用复数. 实现者应使用相应的 Http 动词 GET,POST,PUT,PATCH,DELETE,HEAD 来操作这些资源即可
不规范的的 url, 冗余没有意义, 形式不固定, 不同的开发者还需要了解文档才能调用.
- http://example.com/api/getallUsers //GET 获取所有用户
- http://example.com/api/getuser/1 //GET 获取标识为 1 用户信息
- http://example.com/api/user/delete/1 //GET/POST 删除标识为 1 用户信息
- http://example.com/api/updateUser/1 //POST 更新标识为 1 用户信息
- http://example.com/api/User/add //POST 添加新的用户
规范后的 RESTful 风格的 url, 形式固定, 可读性强, 根据 users 名词和 http 动词就可以操作这些资源. 名词可以使用驼峰命令或者 "_" 分割
- http://example.com/api/users //GET 获取所有用户信息
- http://example.com/api/users/1 //GET 获取标识为 1 用户信息
- http://example.com/api/users/1 //DELETE 删除标识为 1 用户信息
- http://example.com/api/users/1 //Patch 更新标识为 1 用户部分信息, 包含在 div 中
- http://example.com/api/users //POST 添加新的用户
统一返回数据格式
对于合法的请求应该返回统一的数据格式, 对于返回数据, 通常会包含如下字段.
- code-- 即一个整数类型的 HTTP 响应状态码.
- message-- 即返回给前端的信息, 正常返回时是 "success", 当值为 "fail" 或 "error" 时, 用于显示错误信息.
- data-- 即前端需要返回的数据. 当值为 "fail" 或 "error" 时, 设置为 null.
返回成功的响应 JSON 格式:
- {
- "code": 200,
- "message": "success",
- "data": {
- "name": "小明",
- "age": 16,
- "sex": 0
- }
- }
返回失败的响应 JSON 格式:
- {
- "code": 401,
- "message": "error message",
- "data": null
- }
http 状态码
2**: 成功 - 表示请求已被成功接收.
200(成功)用浏览器打开一个网页, 正常情况下都会返回 200HTTP 状态码.
201(创建成功)代表资源创建成功
3**: 重定向(URL 跳转), 要完成请求必须进行更进一步的操作.
300(多种选择)下载一部片, 服务器有 avi,mp4 等格式.
301(永久移动)请求的网页已永久移动到新位置, 自动将请求者转到新位置.
304 (页面未修改) : 按 F5 刷新(第二次访问).
4**: 客户端错误, 请求有语法错误或请求无法实现.
400(错误请求)服务器不理解请求的语法.
401(未授权)没有携带认证信息或携带了错误的认证信息, 而没有通过认证.(未登录时)
403(禁止)携带了正确的认证信息, 服务器认为该用户对该资源无权访问.(https 输成了 http)
404(未找到)请求的内容不存在.
5**: 服务器端错误, 服务器未能实现合法的请求.
500(服务器内部错误)服务器自己出现错误.
502(网关错误)服务器作为网关或代理, 从上游服务器收到无效响应.
503(服务器不可用)服务器超载或停机维护不可用.
查询参数
在请求数据时, 客户端经常会对数据进行过滤和分页等要求, 而这些参数推荐采用 HTTP Query Parameter 的方式实现.
- // 搜索用户, 最近登录
- http://example.com/api/users?recently_login_day=3
- // 搜索用户, 按照注册时间降序
- http://example.com/api/users?sort=register_time_desc
- // 搜索用户, 按照注册时间升序, 活跃度降序
- http://example.com/api/users?sort=register_time_asc,liveness_desc
复杂参数
xxx
来源: http://www.bubuko.com/infodetail-3393623.html