restful规范是一套主流的API规范,目的是将前后端统一规范。节省二者的沟通成本, 提高开发效率,常见的规范有以下9种
1.https协议
在实际项目部署中,使用https协议代替http,目的是为了让接口更加安全
当然https在项目开发中是不相关的
2.域名
对于后端的开发人员,在实现接口的时候,尽可能在域名上加上api的标识,如:
https://api.example.com https://www.example.com/api/
3.版本
对于后端开发人员,API要体现出来版本,便于后期进行版本的管理
https://api.example.com/v1/ https://v1.api.example.com/ https://www.example.com/api/?version=1.1 或者放在请求头中 ...
4.路径
restful规范中认为网络上的一切都是资源,针对资源可以进行增删改查的操作。URL重要使用名词,使用请求方法进行动作上的区分
https://api/users/v1/ GET方法 用户列表 https://api/users/v1/ POST方法 添加用户 https://api/users/(\d+)/v1/ GET方法 获取单条数据 https://api/users/(\d+)/v1/ DELETE方法 删除单条数据 https://api/users/(\d+)/v1/ PUT方法 更新单条全部数据
https://api/users/(\d+)/v1/ PATCH方法 更新单条局部数据
5.请求方法
根据方法不同进行不同的操作
GET: 在服务器获取资源(一项或者多项) POST: 在服务器新建一个资源 PUT: 在服务器上更新资源 PATCH: 在服务器上局部更新资源 DELETE:在服务器上删除资源
6.搜索条件
在URL中通过参数的形式携带搜索条件,常用GET方法
https://api.example.com/v1/users?limit=10 指定返回的数据数量 https://api.example.com/v1/users?offset=10 返回指定记录的其实位置 https://api.example.com/v1/users?page=2&per_page=10 指定第几页以及每页的数量
7.相应数据
针对不同的操作,服务器响应的结果是有所不同的
URL | 方法 | 描述 | 返回的数据 |
/users/ | GET | 获取数据列表 | [{’name‘:'victor'},{'name':'大山'}] |
/users/ | POST | 添加数据 | 返回新添加的数据对象{’name‘:'victor'}, |
/users/(\d+)/ | GET | 获取单条数据 | {’name‘:'victor'} |
/users/(\d+)/ | DELETE | 删除数据 | 返回一个空对象 |
/users/(\d+)/ | PUT | 更新数据 | 返回更新后的数据{’name‘:'victor'} |
/users/(\d+)/ | PATCH | 局部更新 | 返回更新后的数据{’name‘:'victor'} |
当然上面也不会是绝对的,每个公司都会根据自己的业务需求进行适当的调整
8.状态码
API接口除了数据以外,还会携带一些状态码,表示请求的状况,状态码也是公司自行设定的
{ code:400, error:'xxx' }
9.错误处理
当后端响应请求的时候,如果发生错误,也需要将错误返回给客户端
{ code:400, error:'xxx' }
10.案例
该案例仍然是使用Django的写法
路由:
from django.contrib import admin from django.urls import path from student import views urlpatterns = [ path('admin/', admin.site.urls), path('users/<str:version>/students', views.showUsers), path('users/<str:version>/students/<int:pk>', views.showUsers), ]
视图函数
1 from django.shortcuts import render 2 from django.http import JsonResponse 3 4 5 # Create your views here. 6 def showUsers(request, version, pk=None): 7 # 获取版本 8 print(version) 9 # 没有用户ID 10 if not pk: 11 if request.method == "GET": 12 print('获取用户列表') 13 data = { 14 'code': 0, 15 'data': [ 16 { 17 'id': 1, 'name': 'kunmzhao' 18 }, 19 { 20 'id': 2, 'name': 'victor' 21 }, 22 { 23 'id': 3, 'name': '大山' 24 }, 25 ] 26 } 27 elif request.method == "POST": 28 # 从请求体中获取数据,添加导数据库 29 data = { 30 'code': 0, 31 'data': {'id': 4, 'name': 'jerry'} 32 } 33 else: 34 data = { 35 'code': 100, 36 'error': '请求错误' 37 } 38 else: 39 if request.method == "GET": 40 # 获取pk对应的用户数据 41 data = { 42 "code": 0, 43 "data": [{"id": 3, "name": 'kunmzhao'}], 44 } 45 elif request.method == "DELETE": 46 # 删除指定pk下的用户 47 data = { 48 "code": 0, 49 } 50 elif request.method == 'PUT': 51 # 更新数据到数据库 52 data = { 53 "code": 0, 54 "data": [{"id": 4, "name": 'sunny'}], 55 } 56 elif request.method == "PATCH": 57 # 更新数据到数据库 58 data = { 59 "code": 0, 60 "data": [{"id": 5, "name": 'wind'}], 61 } 62 else: 63 data = { 64 "code": 400, 65 "error": "请求错误", 66 } 67 return JsonResponse(data)
在上面的案例中我们使用的是Django中的FBV写法,使用CBV写法如下
路由
from django.urls import path from web import views urlpatterns = [ path("api/<str:version>/students/", views.Users.as_view()), path("api/<str:version>/students/<int:pk>", views.Users.as_view()), ]
视图
from django.http import JsonResponse from django.views import View class Users(View): def get(self,request, version, pk=None): if not pk: # 获取用户列表 info = { "code": 0, "data": [{"id": 1, "name": 'kunmzhao'}], } return JsonResponse(info) # 获取pk对应的用户数据 info = { "code": 0, "data": [{"id": 3, "name": 'victor'}], } return JsonResponse(info) def post(self, request,version): # 新增用户,将用户添加到数据库中 info = { "code": 0, "data": [{"id": 2, "name": 'victor'}], } return JsonResponse(info) def delete(self, request,version,pk): # 删除指定pk下的用户 info = { "code": 0, } return JsonResponse(info) def put(self, request,version,pk): # 更新数据到数据库 info = { "code": 0, "data": [{"id": 4, "name": 'sunny'}], } return JsonResponse(info) def patch(self, request, version, pk): # 更新数据到数据库 info = { "code": 0, "data": [{"id": 5, "name": 'wind'}], } return JsonResponse(info)
标签:code,name,Restful,规范,api,https,data,users From: https://www.cnblogs.com/victor1234/p/16874413.html