无痕5201314
restful API

一，什么是restful

  • rest与技术无关，代表的是一种软件架构分隔，rest是Representational State Transfer的简称，“表征状态转移”
  • rest从资源的角度审视整个网络，它将分布在网络中某个节点的资源通过URL进行标识，客户端应用通过URL来获取资源的表征，获得这些表征致使这些应用转变状态
  • 所有的数据，不管是通过网络获取还是操作数据库获得（增删改查）的数据，都是资源，将一切数据视为资源是rest区别于其他架构分格的本质属性
  • 对于rest这种面向资源的架构分格，有人提出一种全新的结构理念，即：面向资源架构（ROA：Resource Oriented Architecture）对互联网上的任何东西都视为资源，一个url就是一个资源比如：http://www.xxx.com/get_user/

二，什么是API

API就是接口，提供的url，接口有两个用途：

  • 为别人提供服务
  • 前后端分离，一个写vue，一个写后端，他们之间都是通过ajax请求进行数据交互的

三、RESTful API设计

网络应用程序，分为前端和后端两个部分，当前的发展趋势就是前端设备层出不穷（手机，桌面电脑、其他专用设备......）

因此，必须有一种统一的机制，放彼啊NBU同的前端设备与后端进行通信，这导致API架构的流行，RESTful API是目前比较成熟的一套互联网应用程序的API设计理论：

协议：

API与用户的通信协议，总使用Https协议。

域名：

有两种方式:

方式一：尽量将api部署在专用域名（会存在跨域问题）

https://api.example.com

方式二：如果确定api很简单，不会有进一步扩展，可以考虑放在主域名下

https://example,org/api/

版本：

应该将API的版本号放入URL：https://api.example.com/v1/另一种做法是将版本号放在http头信息中，但不如放入url方便和直观；github采用的就是这种做法

路径

路径又称“终点”表示API的具体网址。

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的“集合”，所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括 各种动物和雇员的信息，则它的路径应该设计成：

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

http动词

对于资源的具体操作类型，由http动词表示。

常用的http动词及对应的SQL命令有以下五个：

  • GET(SELECT):从服务器取出资源（一项或多项）。即获取数据
  • POST(CREATE):在服务器新建一个资源，即添加数据。
  • PUT(UPDATE):在服务器更新资源，客户端提供改变后的完整资源，即更新数据
  • PATCH(UPDATE):在服务器更新资源客户端提供改变的属性。即更新数据
  • DELETE(DELETE):在服务器删除资源，即删除数据

两个不常用的：

　　HEAD：获取资源的元数据

　　OPTIONS:获取信息，关于资源的那些属性是客户端可以改变的

过滤信息

如果记录数量很多，服务器不可能豆浆它们返回给用户，API应该提供参数，过滤返回结果。

以下是一些常见的参数：

？limit10:指定返回记录的数量
?offset=10:指定返回记录的开始位置
？page=2&per_page=100:指定第几页，以及每页记得记录数
？sortby=name&order=asc:指定返回结果按照哪个属性排序，以及排序顺序
？animal_type_id=1:指定筛选条件

参数的设计允许存在冗余，即允许API路径和url参数偶尔有重复，比如，GET/zoo/animals与GET/animals?zoo_id=ID的含义是相同的

状态码

服务器向用户返回的状态码和提示信息，常见的有以下这些：

200 OK -[GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）
201 CREATED -[POST/PUT/PAtCH]:用户新建或修改数据成功
202 Accepted -[*]:表示一个请求已经成功进入后台排队（异步任务）
204 NO CONTENT -[DELETE]:用户删除数据成功
400 INVALID REQUEST -[POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作
401 Unauthorized -[*]表示用户没有权限（令牌，用户名，密码错误）
403 Forbidden -[*] 表示用户得到授权，但是访问是被禁止的
404 NOT FOUND -[*] 用户发出的请求针对的是不存在的记录，服务器没有进行操作
406 NOTAcceptable -[GET]用户请求的格式不可获得数据（比如用户请求json格式，但是只有xml）
410 GONE -[GET] 用户请求的资源被永久删除，且不会再得到
422 Unprocesable entity -[POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误
500 INTERNAL SERVER ERROR -[*]服务器发生错误，用户将无法判断发出请求是否成功

　更多详细状态码见官网

错误处理

　如果状态码是4xx,就应该想用户返回出错信息，一般来说，返回的信息中将error作为键名，出错信息作为键值即可

{
    error:"Invalid api key"  
}

 

返回结果

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

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

Hypermedia API 超链接api

RESTful API最好做到Hypermedia，即返回结果提供超链接，联想其他API方法，使得用户不查文档也不知道下一步该做什么

比如，当用户向api.example.com的根目录发出请求，会得到这样的一个文档。

{"link": {
  "rel":   "collection https://www.example.com/zoos",  #表示这个API与当前网址的关系（collection关系，并给出该collection的网址）
  "href":  "https://api.example.com/zoos",  #API路径
  "title": "List of zoos",  #API的标题
  "type":  "application/vnd.yourformat+json"  #返回类型
}}
Hypermedia API的设计被称为HATEOAS，Github的API就是这样的设计。访问api.github。com会得到一个所有可用的API的网址列表

四、基于django实现API

方式一：FBV模式：

全局url
 from app02 import views
 from django.conf.urls import url
 urlpatterns = [
     url('^users/', views.users),
     url('^user/(\d+)', views.user),
 
     url('^users/', views.UsersView.as_view()),
     url('^user/', views.UserView.as_view()),
 ]
app02/url
from django.shortcuts import render,HttpResponse
import json
def uers(request):
      response={'code':1000,'data':None}#code用来表示状态，比如1000代表成功，
      response['data']=[
              {‘name’:'kxl','age':23},
              {'name':'kxllong','age':22}
              {'name':'jingjing','age':20}
        ]   
       return HttpResponse(json.dumps(response))#返回多一条数据
def  user(request,pk):
        if request.method=='GET':
             return HttpResponse(json.dumps({'name':'kxl','age':23}))#返回一条数据
        elif request.method=='POST':
              return HttpResponse(json.dumps({'code':1111}))#返回一条数据
         esif request.method=='PUT':
              pass
         elif request.method=='DELETE':
              pass
View

方式二：CBV

from app02 import views
from django.conf.urls import url
urlpatterns=[
         url('^users/',views.UsersView.as_view()),
         url('^user/',views.UserView.as_view()),
]
urls
from django.views import View
 class UsersView(View):
     def get(self,request):
         response = {'code':1000,'data':None}
         response['data'] = [
             {'name': 'haiyan', 'age': 22},
             {'name': 'haidong', 'age': 10},
             {'name': 'haixiyu', 'age': 11},
         ]
         return HttpResponse(json.dumps(response),stutas=200)
 
 class UserView(View):
     def get(self,request,pk):
         return HttpResponse(json.dumps({'name':'haiyan','age':11}))  #返回一条数据
     def post(self,request,pk):
         return HttpResponse(json.dumps({'code':1111}))  #返回一条数据
     def put(self,request,pk):
         pass
     def delete(self,request,pk):
        pass
复制代码
views

基于django实现的API许多功能都需要我们自己开发，这时候djangorestframwork就给我们提供了方便，直接基于它来返回数据，总之原理都是一样的，就是给一个接口也就是url，让前端的人去请求这个url去获取数据，在页面上显示出来，这样也就达到了前后端分离的效果。

五、基于restframwork框架实现API

自定义认证规则

class MyAuthtication(BasicAuthentication):
        def authenticate(self,request):
                token=request.query_params.get('token')#注意是没有GET的，用queery_params表示
                if token=='kkkkkkkkkk':
                    return ('uuuuuuuu','asdfasdf')#返回user，auth
                raise APIException('认证错误')
class UserView(APIView):
    authentication_classes = [MyAuthtication,]
    def get(self,request,*args,**kwargs):
        print(request.user)
        print(request.auth)
        return Response('用户列表')

 

posted on 2019-11-07 13:35  无痕5201314  阅读(177)  评论(0)    收藏  举报

博客园  ©  2004-2026
浙公网安备 33010602011771号 浙ICP备2021040463号-3 Powered By博客园