1 2 3 4

Restful 规范

一.介绍

首先大家得明白一件事 Restful规范他只是一种规范 是一种设计风格  不是强制性要求 实际开发中可以看业务选择性的遵循其中某些规则

 

 

二. RESTful 具体要求

1、协议

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

2、域名

域名这一块可以写成子域名   也可以写成url(尽可能写成url)

https://api.example.com                         将API部署在专用域名(会存在跨域问题)
https://example.org/api/                        写在url上则API很简单

 

3、版本

版本可以写在url中

URL,如:https://api.example.com/v1/  # 表示第一版 

4 面向资源编程

视网络上任何东西都是资源,均使用名词表示(可复数)

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees 

5 根据method的不同做不同的操作

比如之前的 get_name add_name delete_name update_name的url  
可以直接写成FBV模式 或者CBV模式 如path('people',views.NameView.as_view())

def people(request): if request.method == "get": pass
或者
class PeopleView(view): def get(self,request,*args,**kwargs): pass

  

GET      :从服务器取出资源(一项或多项)
POST    :在服务器新建一个资源
PUT      :在服务器更新资源(客户端提供改变后的完整资源)
PATCH  :在服务器更新资源(客户端提供改变的属性)
DELETE :从服务器删除资源

 

操作资源一般都会涉及到增删改查,我们提供请求方式来标识增删改查动作
<https://api.baidu.com/books> - get请求:获取所有书
<https://api.baidu.com/books/1> - get请求:获取主键为1的书
<https://api.baidu.com/books> - post请求:新增一本书书
<https://api.baidu.com/books/1> - put请求:整体修改主键为1的书
<https://api.baidu.com/books/1> - patch请求:局部修改主键为1的书
<https://api.baidu.com/books/1> - delete请求:删除主键为1的书

  

6 url过滤

通过在url上传参的形式传递搜索条件

https://api.example.com/v1/zoos?limit=10:指定返回记录的数量
https://api.example.com/v1/zoos?offset=10:指定返回记录的开始位置
https://api.example.com/v1/zoos?page=2&per_page=100:指定第几页,以及每页的记录数
https://api.example.com/v1/zoos?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序
https://api.example.com/v1/zoos?animal_type_id=1:指定筛选条件

 

7 状态码

'''
正常响应
响应状态码2xx
  200:常规请求
  201:创建成功
重定向响应 响应状态码3xx   301:永久重定向   302:暂时重定向
客户端异常 响应状态码4xx   403:请求无权限   404:请求路径不存在   405:请求方法不存在
服务器异常 响应状态码5xx   500:服务器异常
更多看这里:http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html 常用状态码列表 '''

 

8 错误处理

状态码是4xx时,应返回错误信息,error当做key

{
    error: "Invalid API key"
}

 

9 返回的结果

针对不同操作,服务器向用户返回的结果应该符合以下规范

GET /collection:返回资源对象的列表(数组)
GET /collection/resource:返回单个资源对象
POST /collection:返回新生成的资源对象
PUT /collection/resource:返回完整的资源对象
PATCH /collection/resource:返回完整的资源对象
DELETE /collection/resource:返回一个空文档

 

10 Hypermedia API

RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。

  

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

  

 

 

  

posted @ 2019-05-23 21:54  犹豫就会拜佛  阅读(160)  评论(0编辑  收藏  举报