RESTful api设计风格

简介

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/ 可以发现,一般的项目加版本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

RESTful api设计风格

上一篇:Web APIs---4. DOM(3)


下一篇:「APIO2012」派遣