REST
介绍
RESTful API 设计
实现API的两种方式
FBV 视图函数
urlpatterns = [
url(r'^user/$', views.user),
url(r'^user/add/$', views.user_add),
url(r'^user/edit/(\d+)/$', views.user_edit),
url(r'^user/del/(\d+)/$', views.user_del),
]
传统的视图函数方式,API接口太多,难以维护。
CBV 视图类
urlpatterns = [
url(r'user/$', views.UserView.as_view()), # GET, POST
url(r'user/(\d+)$', views.UserView.as_view()), # PUT, DELETE
]
根据请求方式的不同,执行视图类中对应的方法。同样是实现增删改查,url少一半。这也是面向资源编程的方式,特点是url中都是名词。
CBV相关知识参考:http://blog.csdn.net/ayhan_huang/article/details/78036501#t11
协议
大神说:API与用户的通信协议,总是使用HTTPs协议
域名
http://api.example.com
尽量使用专用的二级域名http://www.example.com/api/
路由分发。如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。
对应前后端分离的项目,可以这样分配:
前端VUE项目使用域名:http://www.example.com
后端API使用域名:http://api.example.com
版本
应该将API的版本号放入URL。
比如:https://www.example.com/api/v1/
v1是版本信息
路径
路径又称”终点”(endpoint),表示API的具体网址。
在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的”集合”(collection),所以API中的名词也应该使用复数。
举例来说,有一个API提供动物园(zoo)的信息,还包括各种动物和雇员的信息,则它的路径应该设计成下面这样。
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
method
- GET :从服务器取出资源(一项或多项)
- POST :在服务器新建一个资源
- PUT :在服务器更新资源(客户端提供改变后的完整资源,全部更新)
- PATCH :在服务器更新资源(客户端提供改变的属性,局部更新)
- DELETE :从服务器删除资源
- HEAD:和GET一样,只是只返回响应首部,不返回响应体,用于确认资源的信息
- OPTIONS:查询支持的方法,复杂请求的预检会用到。
比如:
- GET /zoos:列出所有动物园
- POST /zoos:新建一个动物园
- GET /zoos/ID:获取某个指定动物园的信息
- PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)
- PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)
- DELETE /zoos/ID:删除某个动物园
- GET /zoos/ID/animals:列出某个指定动物园的所有动物
- DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物
状态码
HTTP状态码负责表示客户端HTTP请求的返回结果,标记服务端的处理是否正常,通知出现的错误等工作。
状态码类别
状态码 | 类别 | 原因短语 |
---|---|---|
1XX | Informational 信息性状态码 | 接收的请求正在处理 |
2XX | Success 成功状态码 | 请求正常处理完毕 |
3XX | Redirection 重定向状态码 | 需要进行附加操作以完成请求 |
4XX | Client Error 客户端错误状态码 | 服务器无法处理请求 |
5XX | Server Error 服务器错误状态码 | 服务器处理请求出错 |
常用状态码一览
- 200 OK:客户端发来的请求在服务端被正常处理了。
- 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
- 202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
- 204 NO CONTENT :请求已成功处理,但响应中不包含响应体。比如 请求方式为[DELETE]时,表示用户删除数据成功。
- 206 Partial Content: 服务器成功执行了客户端的范围请求。响应中包含由Content-Range首部字段指定范围的实体内容
- 301 Moved Permanently: 永久性重定向,请求的资源已被分配了新的URI。应该按Location首部字段提示的URI访问。
- 302 Found, 303 See Other, 307 Temporary Redirect 都是临时性重定向,请求的资源已被临时分配了新的URI,希望用户本次使用新的URI访问。标准不太统一,每种浏览器可能出现不同的情况,了解即可。
- 304 Not Modified: 这个比较特殊,和重定向没有关系,表示服务器资源未改变,可直接使用客户端缓存。
- 400 Bad Request:用户发出的请求报文中存在语法错误,需要修改请求内容后再发送。
- 401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
- 403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
- 404 NOT FOUND - [*]:服务器无法找到请求的资源。或者在服务器拒绝请求且不想说明理由时使用
- 406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
- 410 Gone - [GET]:用户请求的资源被永久删除,且不会再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
- 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,可能外web应用存在bug。
- 503 Service Unavailable: 服务器正忙
状态码有限,可以再约定code,表示更细的状态:
def get(self, request, *args, **kwargs):
res = {
'code': 1001, 'error': None}
try:
print('do something...')
except Exception as e:
res['error'] = str(e)
return JsonResponse(res, status=500)
错误处理
如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。
{
error: "Invalid API key"
}
提供error key,显示详细错误信息
过滤
如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果
- ?limit=1:指定返回记录的数量
- ?offset=10:指定返回记录的开始位置
- ?page=2$per_page=10:指定第几页,以及每页的记录数
- ?sortby=name$order=asc:指定返回结果按照哪个属性排序,以及排序顺序
- ?id=10:指定筛选条件
返回结果
针对不同操作,服务器向用户返回的结果应该符合以下规范。
- GET /collection:返回资源对象的列表(数组)
- GET /collection/resource:返回单个资源对象
- POST /collection:返回新生成的资源对象
- PUT /collection/resource:返回完整的资源对象
- PATCH /collection/resource:返回完整的资源对象
- DELETE /collection/resource:返回一个空文档
Hypermedia
RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。
比如,当用户向api.example.com的根目录发出请求,会得到这样一个文档。
{
"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
上面代码表示,文档中有一个link属性,用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系(collection关系,并给出该collection的网址),href表示API的路径,title表示API的标题,type表示返回类型。
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计,访问api.github.com会得到一个所有可用API的网址列表:
{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
# ...
}
从上面可以看到,如果想获取当前用户的信息,应该去访问api.github.com/user,然后就得到了下面结果:
{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3"
}
上面代码表示,服务器给出了提示信息,以及文档的网址。
Django REST framework
通过Django本身也可以实现API设计,只是相对要麻烦些。Django REST framework基于Django进行了丰富,能更方便的实现API设计。
基本使用
settings
INSTALLED_APPS = [
# ...
'rest_framework',
]
路由
urlpatterns = [
url(r'user/$', views.UserView.as_view()), # GET, POST
url(r'user/(?P<pk>\d+)/$', views.UserView.as_view()), # PUT, DELETE
]
视图
from rest_framework.views import APIView
from django.http import JsonResponse
class UsersView(APIView):
def dispatch(self, request, *args, **kwargs):
"""请求到来之后,首先执行dispatch方法,dispatch方法根据请求方式的不同,反射执行 get/post/put等方法"""
return super().dispatch(request, *args, **kwargs)
def get(self, request, *args, **kwargs):
res = {
'code': '10001',
'data': [], # 字典元素
'error': None
}
# return HttpResponse(json.dumps(res), status=200, content_type='application/json')
# 如果是HttpResponse,需要手动json, 并且指定content_type
return JsonResponse(res, status=200)
def post(self, request, *args, **kwargs):
pass
def put(self, request, *args, **kwargs):
pk = kwargs.get('pk') # 获取url命名分组传参
pass
def delete(self, request, *args, **kwargs):
pass
生命周期
中间件
路由系统
- .as_view() 方法:
return csrf_exempt(view)
- .as_view() 方法:
CBV视图类
执行dispatch方法
二次封装request
def initialize_request(self, request, *args, **kwargs): parser_context = self.get_parser_context(request) # return Request( request, parsers=self.get_parsers(), # 解析器 authenticators=self.get_authenticators(), # 认证 negotiator=self.get_content_negotiator(), # 选择器 parser_context=parser_context # 字典:view和参数 )
try:
获取版本,认证,权限,节流
def initial(self, request, *args, **kwargs): """ Runs anything that needs to occur prior to calling the method handler. """ self.format_kwarg = self.get_format_suffix(**kwargs) # Perform content negotiation and store the accepted info on the request # 根据用户请求选择 neg = self.perform_content_negotiation(request) request.accepted_renderer, request.accepted_media_type = neg # Determine the API version, if versioning is in use. # 获取版本信息,和处理版本的类的对象 version, scheme = self.determine_version(request, *args, **kwargs) request.version, request.versioning_scheme = version, scheme # Ensure that the incoming request is permitted # 认证 self.perform_authentication(request) # 权限 self.check_permissions(request) # 控制访问次数(每天访问10次) self.check_throttles(request)
根据请求方法反射执行 GET/POST/DELETE…
except:
- 处理异常
返回响应
版本
查看源码可知,Django REST framework一共支持5种版本控制方式:
- AcceptHeaderVersioning
- URLPathVersioning
- NamespaceVersioning
- HostNameVersioning
- QueryParameterVersioning
导入及使用方式:
from rest_framework.versioning import URLPathVersioning
class TestView(APIView):
versioning_class = URLPathVersioning # 指定版本
pass
版本控制中通用的settings全局配置:
REST_FRAMEWORK = {
# 'DEFAULT_VERSION': 'v1', # 默认版本
# 'ALLOWED_VERSIONS': ['v1', 'v2'], # 允许的版本
}
下面介绍其中两种比较常用获取版本的方式。
基于查询字符串传参
settings配置
REST_FRAMEWORK = {
'VERSION_PARM': 'version' # 配置从URL中获取值的key
}
urls配置
urlpatterns = [
url(r'test', views.TestView.as_view(), name='test')
]
CBV
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.versioning import QueryParameterVersioning
class TestView(APIView):
versioning_class = QueryParameterVersioning # 指定版本
def get(self, request, *args, **kwargs):
# 获取版本
print(request.version)
# 获取版本管理的类
print(request.versioning_scheme)
# 反向生成url
reverse_url = request.versioning_sch