RESTful API設計規範

一個訂單的功能，增刪改查須要四個視圖函數，對應四個 url

views.py

def get_order(request):
    return HttpResponse('')

def add_order(request):
    return HttpResponse('')

def del_order(request):
    return HttpResponse('')

def update_order(request):
    return HttpResponse('')

urls.py

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^get_order/', views.get_order),
    url(r'^add_order/', views.add_order),
    url(r'^del_order/', views.del_order),
    url(r'^update_order/', views.update_order),
]

這樣一旦功能多了起來，對應的 url 也就多了，顯然很差處理。如今只寫一個 url，對應四個功能，因而要在視圖函數中判斷

urls.py

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^order/', views.order),
]

views.py

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('刪除訂單')

這就是 restful 規範之一：根據 method 不一樣從而作不一樣的操做

上面的方法也能夠基於 CBV 來實現：

urls.py

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^order/', views.OrderView.as_view())
]

views.py

from django.views import View

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('刪除訂單')

RESTful Api設計規範

協議

API 與用戶的通訊協議，老是使用 HTTPs 協議

域名

應該儘可能將 API 部署在專用域名之下，若是肯定 API 很簡單，不會有進一步的擴展，能夠考慮放在主域名之下。

版本

• 應該將API的版本放在URL中：https://www.qiuxirufeng.cn/api/v1.0

• 將版本號放在HTTP頭信息中：https://www.qiuxirufeng.cn/students

路徑

表示 API 的具體網址，每一個網址表明一種資源，因此網址中不能有動詞，只能有名詞，而且所用的名詞每每與數據庫的表名對應。數據庫中的表示記錄同種數據的集合，因此 API 中的名詞也應該使用複數。

示例：獲取全部學生

• 錯誤寫法：https://www.qiuxirufeng.cn/api/v1.0/getStudents/
• 正確寫法：https://www.qiuxirufeng.cn/api/v1.0/students/

請求方法（method）

方式	解釋
GET	從服務器獲取資源（一項或者多項）
POST	在服務器新建一個資源
PUT	在服務器更新資源（客戶端提供改變後的完整資源）
PATCH	在服務器更新資源（客戶端提供改的屬性）
DELETE	從服務器刪除資源
HEAD	獲取資源的元數據
OPTIONS	獲取信息，關於資源的哪些屬性是客戶端能夠改變的

示例

描述	方式
列出全部班級	GET /grades/
獲取某個指定班級編號的信息	GET /grades/id
列出某個指定編號的班級的全部學生	GET /grades/id/students/
獲取某個指定編號的學生信息	GET /students/id
建立一個學生	POST /students/
更新某個指定學生的信息(信息所有由客戶端提供)	PUT /students/id
刪除某個指定編號的學生	DELETE /students/id
刪除某個指定班級的下的全部學生	DELETE /grades/id/students/

過濾信息

若是資源數較多，服務器不能將全部數據一次所有返回給客戶端，API 應該提供參數，經過在 url 上傳參的形式傳遞搜索條件，過濾返回結果

示例

描述	方式
指定返回記錄的數量	GET /students/?limit=
指定返回記錄的開始位置	GET /students/?offset=
指定返回第幾頁數據，以及每頁的記錄數	GET /students/?page=&per_page=
指定返回結果按照哪一個屬性排序，以及排序的順序	GET /students/?sortby=&order=
指定篩選條件	GET /students/?student_age_gt=

注意：參數的設計容許存在冗餘，即容許 API 路徑和 URL 參數偶爾有重複

狀態碼

服務器向客戶端返回的狀態碼和提示信息

錯誤處理

若是錯誤碼是 4xx，就應該向用戶返回錯誤信息，通常來講，返回的信息中將 error 做爲鍵名，出錯的信息做爲鍵值便可

{
    error: 'Invalid API KEY',
}

響應結果

針對不一樣的操做，服務器向用戶返回結果應該符合規範

方式	描述
GET /students/	返回資源對象的列表
GET /students/id/	返回單個資源對象
POST /students/	返回新生成的資源對象
PUT /students/	返回完整的資源對象
PATCH /students/	返回完整的資源對象
DELETE /students/id/	返回一個空文檔

使用連接相關的資源（Hypermedia）

RESTful API 最好作到 Hypermedia，即返回結果中提供連接，鏈向了其餘的 API 方法，使得用戶不查看文檔，也知道下一步應該作什麼

示例

{
    link:" www.qiuxirufeng.cn/grades/"
}
{
    "link":{
        "rel":"collection www.qiuxirufeng.cn/index/",
        "href":"www.qiuxirufeng.cn/grades/",
        "title":"List of Grades",
        "type":"application/json",
    }
}

'''
rel：表示這個 API 與當前網址的關係
href：表示 API 路徑
title：表示 API 的標題
type：表示返回的類型

'''

其餘：服務器返回的數據儘可能使用 json 格式，避免使用 xml 格式