RESTful接口規範

一. 什麼是RESTful 

  • REST與技術無關,表明的是一種軟件架構風格,REST是Representational State Transfer的簡稱,中文翻譯爲「表徵狀態轉移」
  • REST從資源的角度類審視整個網絡,它將分佈在網絡中某個節點的資源經過URL進行標識,客戶端應用經過URL來獲取資源的表徵,得到這些表徵導致這些應用轉變狀態
  • REST與技術無關,表明的是一種軟件架構風格,REST是Representational State Transfer的簡稱,中文翻譯爲「表徵狀態轉移」
  • 全部的數據,不過是經過網絡獲取的仍是操做(增刪改查)的數據,都是資源,將一切數據視爲資源是REST區別與其餘架構風格的最本質屬性
  • 對於REST這種面向資源的架構風格,有人提出一種全新的結構理念,即:面向資源架構(ROA:Resource Oriented Architecture)

二. RESTful API設計

  • API與用戶的通訊協議,老是使用HTTPs協議
  • 域名 
    • https://api.example.com                         儘可能將API部署在專用域名(會存在跨域問題)
    • https://example.org/api/                        API很簡單
  • 版本
    • URL,如:https://api.example.com/v1/
    • 請求頭                                                  跨域時,引起發送屢次請求
  • 路徑,視網絡上任何東西都是資源,均使用名詞表示(可複數)
    • https://api.example.com/v1/zoos
    • https://api.example.com/v1/animals
    • https://api.example.com/v1/employees
  • method
    • GET      :從服務器取出資源(一項或多項)
    • POST    :在服務器新建一個資源
    • PUT      :在服務器更新資源(客戶端提供改變後的完整資源)
    • PATCH  :在服務器更新資源(客戶端提供改變的屬性)
    • DELETE :從服務器刪除資源
  • 過濾,經過在url上傳參的形式傳遞搜索條件
    • https://api.example.com/v1/zoos?limit=10:指定返回記錄的數量
    • https://api.example.com/v1/zoos?offset=10:指定返回記錄的開始位置
    • https://api.example.com/v1/zoos?page=2&per_page=100:指定第幾頁,以及每頁的記錄數
    • https://api.example.com/v1/zoos?sortby=name&order=asc:指定返回結果按照哪一個屬性排序,以及排序順序
    • https://api.example.com/v1/zoos?animal_type_id=1:指定篩選\
  • 狀態碼   
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 - [*] 表示用戶獲得受權(與401錯誤相對),可是訪問是被禁止的。
404 NOT FOUND - [*]:用戶發出的請求針對的是不存在的記錄,服務器沒有進行操做,該操做是冪等的。
406 Not Acceptable - [GET]:用戶請求的格式不可得(好比用戶請求JSON格式,可是隻有XML格式)。
410 Gone -[GET]:用戶請求的資源被永久刪除,且不會再獲得的。
422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個對象時,發生一個驗證錯誤。
500 INTERNAL SERVER ERROR - [*]:服務器發生錯誤,用戶將沒法判斷髮出的請求是否成功。
狀態碼
  • 返回結果,針對不一樣操做,服務器向用戶返回的結果應該符合如下規範。
GET /collection:返回資源對象的列表(數組)
GET /collection/resource:返回單個資源對象
POST /collection:返回新生成的資源對象
PUT /collection/resource:返回完整的資源對象
PATCH /collection/resource:返回完整的資源對象
DELETE /collection/resource:返回一個空文檔
  • Hypermedia API  超媒體API

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

好比,當用戶向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的網址列表。git

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}

從上面能夠看到,若是想獲取當前用戶的信息,應該去訪問api.github.com/user,而後就獲得了下面結果。github

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

三 基於Django實現API

1 FBV模式

 1 from django.contrib import admin
 2 
 3 from django.conf.urls import url, include
 4 from app01 import views
 5 from app02 import views
 6 
 7 urlpatterns = [
 8     url('admin/', admin.site.urls),
 9     # path('hosts/',views.HostView.as_view()),
10     url('app02/', include('app02.urls'))
11 ]
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
app_url
from django.shortcuts import render,HttpResponse

# Create your views here.
import json

def users(request):
    response = {'code':1000,'data':None}  #code用來表示狀態,好比1000表明成功,1001表明
    response['data'] = [
        {'name':'harry','age':22},
        {'name':'sam','age':10},
        {'name':'jerry','age':11},
    ]
    return HttpResponse(json.dumps(response))  #返回多條數據

def user(request,pk):
    if request.method =='GET':
        return HttpResponse(json.dumps({'name':'harry','age':11}))  #返回一條數據
    elif request.method =='POST':
        return HttpResponse(json.dumps({'code':1111}))  #返回一條數據
    elif request.method =='PUT':
        pass
    elif request.method =='DELETE':
        pass

View
View

2 CBV模式

1 from app02 import views
2 from django.conf.urls import url
3 urlpatterns = [
4     url('^users/', views.UsersView.as_view()),
5     url('^user/', views.UserView.as_view()),
6 ]
url
 1 from django.views import View
 2 class UsersView(View):
 3     def get(self,request):
 4         response = {'code':1000,'data':None}
 5         response['data'] = [
 6             {'name': harry', 'age': 22},
 7             {'name': 'sam', 'age': 10},
 8             {'name': 'jerry', 'age': 11},
 9         ]
10         return HttpResponse(json.dumps(response),stutas=200)
11 
12 class UserView(View):
13     def get(self,request,pk):
14         return HttpResponse(json.dumps({'name':'harry','age':11}))  #返回一條數據
15     def post(self,request,pk):
16         return HttpResponse(json.dumps({'code':1111}))  #返回一條數據
17     def put(self,request,pk):
18         pass
19     def delete(self,request,pk):
20         pass
21 
22 views
View

四 基於Django Rest Framework框架實現

基於django實現的API許多功能都須要咱們本身開發,這時候djangorestframework就給咱們提供了方便,直接基於它來返回數據,總之原理都是同樣的,就是給一個接口也就是url,讓前端的人去請求這個url去獲取數據,在頁面上顯示出來。這樣也就達到了先後端分離的效果。下面咱們來看看基於Django Rest Framework框架實現

具體使用方式參考:Django restframework的使用django

相關文章
相關標籤/搜索