浅谈restful规范

浅谈Restful规范

restful:

• 即Representational State Transfer 翻译:“表述性状态传输"或者"表述性状态-转移”。
• 一种软件架构的规范、约束、原则;符合这种规范，就称之为restful规范。
• 只是思想跟技术无关。
• 优点:面向资源、接口明确、数据简单等。
• 以上仅个人观点非官方

restful十大规范:

一.API与用户的通信协议使用HTTPS协议(安全)。

二.域名:

	1.子域名方式:
		www.limingzq.com
		api.limingzq.com
		域名或端口不同会存在跨域问题
		客户端可请求，服务端可返回，返回后客户端禁止；需自行解决跨域问题。

	2.url方式：
		www.limingzq.com
		www.limingzq.com/api/
		将API部署在专用域名

三.版本更新:

	1.版本写在url上：
		https://www.limingzq.com/api/v1/
		https://www.limingzq.com/api/v2/
	2.请求头;跨域时引发,发送多次请求。

四.路径：

	1.网络上任何东西都是资源，使用名词表示（可复数）。
		https://www.limingzq.com/api/v1/orders # V1版本订单信息url
		https://www.limingzq.com/api/v1/clients # V1版本客户信息url

五.method请求方法：

	1.HTTP 8种请求方法:
		GET:获取服务端资源
		HEAD:获取服务端请求头
		POST:创建服务端资源
		PUT:更新服务端资源（完整资源更新-坑！）
		PATCH:更新服务端资源（局部资源更新）
		DELETE:删除服务端资源
		TRACE:测试和诊断服务端
		OPTIONS:允许客户端查看服务器性能
		CONNECT:HTTP/1.1协议中预留给能够将连接改为管道方式的代理服务器

	2.根据客户端method请求方法不同做不同的操作/示例：
	# django路由层:
	path('order_fbv/', views.order, name='FBV-order-view'),
	path('order_cbv/', views.OrderView.as_view(), name='CBV-order_view'),
	# django视图层:
	from django.http import HttpResponse
	from django.views.decorators.csrf import csrf_exempt, csrf_protect
	from django.views import View
	#------------------ FBV ------------------
	@csrf_exempt  # FBV不做csrf_token验证 反之@csrf_protect
	def order(request):
		if request.method == 'GET':
			return HttpResponse('获取订单')
		elif request.method == 'POST':
			return HttpResponse('创建订单')
		elif request.method == 'PUT':
			return HttpResponse('更新订单')
		elif request.method == 'DELETE':
			return HttpResponse('删除订单')
		else:
			return HttpResponse('非法操作')
	#------------------ FBV ------------------
	@method_decorator(csrf_exempt, name='dispatch')  # 1.CBV不做csrf_token验证(单独方法无效)反之csrf_protect。
	class OrderView(View):
		def get(self, request, *args, **kwargs):				
			return HttpResponse('获取订单')
		def post(self, request, *args, **kwargs):
			return HttpResponse('提交订单')
		def put(self, request, *args, **kwargs):
			return HttpResponse('更新订单')
		def delete(self, request, *args, **kwargs):
			return HttpResponse('删除订单')

六.过滤:

	1.url上传递参数；筛选条件。
		# GET获取服务端订单信息状态码=1、页数=2的资源。
		www.limingzq.com/api/v1/orders/?status=1;page=2		
		# GET获取服务端客户信息数量=10的资源。
		www.limingzq.com/api/v1/clients/?limit=10

七.状态码:

	1.常见状态码:
		200:请求服务端获取资源成功
		201:新建或修改数据成功
		202:请求已经进入后台排队但为处理完成(异步任务)
		204:删除数据成功
		206:服务端成功处理
		301:永久重定向
		302:临时重定向
		401:用户没有权限访问(token令牌、账号或密码错误/django常见csrf_token认证)
		403:服务端得到授权但拒绝访问
		404:服务端资源不存在
		406:请求格式错误(客户端json格式请求，服务端只有xml格式)
		408:服务端等待客户端请求超时
		410:客户端请求资源已在服务端永久删除/不存在
		500:服务端内部错误
		501:服务端不支持客户端请求
		503:服务端超负载或停机维护
		505:服务端不支持HTTP协议请求
	# 更多参考:https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

	2.状态码应与自定义code,message相结合:
		class OrderView(View):
			def get(self, request, *args, **kwargs):
				ret = {
					'code': 1000,
					'message': 'GET响应成功,获取到服务端订单资源'
				}
				return HttpResponse(json.dumps(ret), status=200)

八.错误信息处理:

	1.示例:
		# 'error'作key
		ret = {'error':'非法请求'}
		return HttpResponse(json.dumps(ret))

九.返回结果处理:

	1.示例:
		GET /order/ 		返回所有订单资源
		GET /order/?id=1 	返回id=1的订单资源
		POST /order/ 		创建后返回创建的订单资源	
		PUT  /order/1/		更新后返回id=1订单资源(同上GET的URL)
		DELETE /order/		返回空

十.Hypermedia API(超级传播连接):

	1.根据业务场景,返回结果提供详情链接。
	2.示例:
		用户订单列表：
		url :https:www.limingzq.com/api/v1/orders/
		用户订单详情url:'省去拼接'
		[
			{
			id:1,
			name:'phone12MaxPro',
			ram:256,
			color:'red',
			url:'https:www.limingzq.com/api/v1/orders/1/'
			},
			{
			id:2,
			name:'phone6s',
			ram:32,
			color:'gold',
			url:'https:www.limingzq.com/api/v1/orders/2/'
			},
		]