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。

接口的用途:

　　1.為別人提供服務

　　2.前后端分離，練習前台頁面與后台數據庫的媒介

接口的組成:

　　url:url鏈接

　　請求參數: 前台按照指定的key提供數據給后台

　　響應數據: 后台與數據庫交互后將數據反饋給前台

RESTful API 規范

接口規范:就是為了采用不同的后台語言，也能使用同樣的接口獲取到同樣的前台數據

如何寫接口：接口規范是 規范化書寫接口的，寫接口要寫url,響應數據

　　注：如果將請求參數也納入考量范圍，那就是再寫 接口文檔

 

兩大部分

url

1)用api關鍵字標識接口url
    api.baidu.com   |   www.baidu.com/api

2)接口數據安全性決定優先選擇https協議

3)如果一個接口有多版本存在，需要再url中標識體現
    api.baidu.com/v1/...    |   api.baidu.com/v2/...

4)接口操作的數據源稱之為資源，在url中 一般采用資源復數形式，一個接口可以概括對該資源的多種操作方式
   api.baidu.com/books     |   api.baidu.com/books/(pk)

5)請求方式有多種,用一個url處理如何保證不混亂  -通過請求方式標識操作資源的方式
    /books        get            獲取所有
    /books        post                增加一個(多個)
    /books/(pk)    delete        刪除一個
    /books/(pk)    put            整體更新一個
    /books/(pk)    patch        局部更新一個


6)資源往往涉及到數據的各種操作方式-篩選，排序，限制
    api.baidu.com/books/?search=西&ordering=-price&limit=3

 

 

響應數據

1) http請求的響應會有響應狀態碼，接口用來返回操作的資源數據，可以擁有 操作數據結果的 狀態碼
    status  0(操作資源成功)  1(操作資源失敗)  2(操作資源成功，但沒匹配結果)
    注：資源狀態碼不像http狀態碼，一般都是后台與前台或是客戶約定的
    
2) 資源的狀態碼文字提示
    status  ok    '賬號有誤'  '密碼有誤'  '用戶鎖定'
    
3) 資源本身
    results
    注：刪除資源成功不做任何數據返回(返回空字符串)
    
4) 不能直接放回的資源(子資源、圖片、視頻等資源)，返回該資源的url鏈接

 

 

 

 

 

基於restful規范的原生Django接口

主路由:url.py

from django.conf.urls import url, include
from django.contrib import admin


urlpatterns = [
    url(r'^admin/', admin.site.urls),
    # 路由分發
    url(r'^api/', include('api.urls'))
]

 

api組件的子路由:api/url.py

from django.conf.urls import url

from . import views
urlpatterns = [
    url(r'^books/', views.Book.as_view()),
    url(r'^books/(?P<pk>.*)/$', views.Book.as_view()),
]

 

模型層:model.py

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=64)
    price = models.DecimalField(max_digits=5, decimal_places=2)

    class Meta:
        db_table = 'old_boy_book'
        verbose_name = '書籍'
        verbose_name_plural = verbose_name

    def __str__(self):
        return '《%s》' % self.title

 

后台層: admin.py

from django.contrib import admin

from . import models

admin.site.register(models.Book)

 

視圖層:views.py

from django.http import JsonResponse

from django.views import View
from . import models


# 六大基礎接口：獲取一個 獲取所有 增加一個 刪除一個 整體更新一個 局部更新一個
# 十大接口：群增 群刪 整體改群改 局部改群改
class Book(View):
    def get(self, request, *args, **kwargs):
        pk = kwargs.get('pk')
        if not pk:  # 群查
            # 操作數據庫
            book_obj_list = models.Book.objects.all()
            # 序列化過程
            book_list = []
            for obj in book_obj_list:
                dic = {}
                dic['title'] = obj.title
                dic['price'] = obj.price
                book_list.append(dic)
            # 響應數據
            return JsonResponse({
                'status': 0,
                'msg': 'ok',
                'results': book_list
            }, json_dumps_params={'ensure_ascii': False})
        else:  # 單查
            book_dic = models.Book.objects.filter(pk=pk).values('title', 'price').first()
            if book_dic:
                return JsonResponse({
                    'status': 0,
                    'msg': 'ok',
                    'results': book_dic
                }, json_dumps_params={'ensure_ascii': False})
            return JsonResponse({
                'status': 2,
                'msg': '無結果',
            }, json_dumps_params={'ensure_ascii': False})


    # postman可以完成不同方式的請求：get | post | put ...
    # postman發送數據包有三種方式：form-data | urlencoding | json
    # 原生django對urlencoding方式數據兼容最好
    def post(self, request, *args, **kwargs):
        # 前台通過urlencoding方式提交數據
        try:
            book_obj = models.Book.objects.create(**request.POST.dict())
            if book_obj:
                return JsonResponse({
                    'status': 0,
                    'msg': 'ok',
                    'results': {'title': book_obj.title, 'price': book_obj.price}
                }, json_dumps_params={'ensure_ascii': False})
        except:
            return JsonResponse({
                'status': 1,
                'msg': '參數有誤',
            }, json_dumps_params={'ensure_ascii': False})

        return JsonResponse({
            'status': 2,
            'msg': '新增失敗',
        }, json_dumps_params={'ensure_ascii': False})

 

 

 

Postman接口工具

官網下載安裝

get請求,攜帶參數采用 Params

post等請求，提交數據包可以采用三種方式:form-data,urlencoding,json

所有請求都可以攜帶請求頭