Knowledge

QiShunwang

知识分享

Django(43)restful接口规范

2021/6/3 13:27:17    来源:

restful接口规范

  什么是接口规范?接口规范就是为了采用不同的后台语言,也能使用同样的接口获取到同样的数据。如何写接口:接口规范是规范化书写接口的,写接口要写url、响应数据
​  注:如果将请求参数也纳入考量范围,那就是在写接口文档
 

url

restful接口的url规范,遵循以下6个规范
 

1.用关键字标识接口url

比如登录的接口,可以用下面的url,这样我们阅读的时候,一眼就能看出这个是登录接口

www.baidu.com/login/

 

2.接口数据安全性决定优先选择https协议

 

3.如果一个接口有多版本存在,需要在url中标识体现

假如我们刚开发一个后台,那第一个版本就是v1

api.baidu.com/v1/

后面接口需要升级,那么就将接口升级为v2

api.baidu.com/v2/

 

4.接口操作的数据源称之为资源,在url中一般采用资源复数形式,一个接口可以概括对该资源的多种操作方式

获取全部书籍

api.baidu.com/books

获取指定的书籍

api.baidu.com/books/(pk)

 

5.请求方式有很多种,用一个url处理如何保证不混乱 - 通过请求方式标识操作资源的方式

获取所有书籍,使用get请求

/books/

增加一本书籍,使用post请求

/books/

删除一本书籍,使用delete请求

/books/(pk)

整体更新一本书籍的内容,使用put请求

/books/(pk)

局部更新一本书籍的一个字段,使用patch请求

/books/(pk)

 

6.资源往往涉及数据的各种操作方式 - 筛选、排序、限制

api.baidu.com/books/?search=jkc&ordering=price&limit=3

 

响应数据

响应数据遵循以下4个规范
 

1.http请求的响应会有响应状态码,接口用来返回操作的资源数据,可以拥有操作数据结果的状态码

status    0(操作资源成功)    1(操作资源失败)    2(操作资源成功,但没匹配结果)

注:资源状态码不像http状态码,一般是后台与前台或者是客户约定的
 

2. 资源的状态码文字提示

status    ok    '账号有误'    '密码有误'    '用户锁定'

 

3. 资源本身

data: {
    业务数据
}

 

4. 不能直接返回的资源(子资源、图片、视频等资源),返回该资源的url链接

文章引用:http://www.qishunwang.net/knowledge_show_146249.aspx