Django高級篇一RESTful架構及API設計

1、什麼是RESTful架構？

    經過互聯網通訊，創建在分佈式體系上"客戶端/服務器模式」的互聯網軟件，具備高併發和高延時的特色。
簡單的來講，就是用開發軟件的模式開發網站。網站開發，徹底能夠採用軟件開發的模式。
可是傳統上，軟件和網絡是兩個不一樣的領域，不多有交集；軟件開發主要針對單機環境，網絡則主要研究系統之間的通訊。
互聯網的興起，使得這兩個領域開始融合，如今咱們必須考慮，如何開發在互聯網環境中使用的軟件。
    RESTful架構，就是目前最流行的一種互聯網軟件架構。它結構清晰、符合標準、易於理解、擴展方便，因此正獲得愈來愈多網站的採用。

2、RESTful架構

1）起源
    REST這個詞，是Roy Thomas Fielding在他2000年的博士論文中提出的。
    （Fielding，HTTP協議（1.0版和1.1版）的主要設計者、Apache服務器軟件的做者之一）Fielding將他對互聯網軟件的架構原則，
    定名爲REST，即Representational State Transfer的縮寫。我對這個詞組的理解是"表現層狀態轉化"。
    若是一個架構符合REST原則，就稱它爲RESTful架構。

2）名稱
    Fielding將他對互聯網軟件的架構原則，定名爲REST，即Representational State Transfer的縮寫。
    我對這個詞組的翻譯是"表現層狀態轉化"。若是一個架構符合REST原則，就稱它爲RESTful架構。
    要理解RESTful架構，最好的方法就是去理解Representational State Transfer這個詞組究竟是什麼意思，
    它的每個詞表明瞭什麼涵義。若是你把這個名稱搞懂了，也就不難體會REST是一種什麼樣的設計。    
    
3）資源（Resource）
　　REST的名稱"表現層狀態轉化"中，省略了主語。"表現層"其實指的是"資源"（Resources）的"表現層"。
　　資源，網絡上的任何一個圖片，一組數據，一首歌曲都是資源。你能夠經過一個特定的URL指向它，
    若是你想獲取這個資源，訪問它對應的URL就能夠了。而在RESTful中，上網就是，互聯網上各類資源的互動。
　　
4）表現層（Representation）
　　"資源"是一種信息實體，它能夠有多種外在表現形式。咱們把"資源"具體呈現出來的形式，叫作它的"表現層"（Representation）。
    好比，文本能夠用txt格式表現，也能夠用HTML格式、XML格式、JSON格式表現，
    甚至能夠採用二進制格式；圖片能夠用JPG格式表現，也能夠用PNG格式表現。
　　URI只表明資源的實體，不表明它的形式。嚴格地說，有些網址最後的".html"後綴名是沒必要要的，
    由於這個後綴名錶示格式，屬於"表現層"範疇，而URI應該只表明"資源"的位置。它的具體表現形式，
    應該在HTTP請求的頭信息中用Accept和Content-Type字段指定，這兩個字段纔是對"表現層"的描述。

5）狀態轉化（State Transfer）
　　訪問一個網站，就表明了客戶端和服務器的一個互動過程。在這個過程當中，勢必涉及到數據和狀態的變化。
    互聯網通訊協議HTTP協議，是一個無狀態協議。這意味着，全部的狀態都保存在服務器端。所以，若是客戶端想要操做服務器，
    必須經過某種手段，讓服務器端發生"狀態轉化"（State Transfer）。而這種轉化是創建在表現層之上的，因此就是"表現層狀態轉化"。
　　客戶端用到的手段，只能是HTTP協議。具體來講，就是HTTP協議裏面，四個表示操做方式的動詞：GET、POST、PUT、DELETE。
    它們分別對應四種基本操做：GET用來獲取資源，POST用來新建資源（也能夠用於更新資源），PUT用來更新資源，DELETE用來刪除資源。

6）總結
　　綜合上面的解釋，咱們總結一下什麼是RESTful架構：
　　1）每個URI表明一種資源；
　　2）客戶端和服務器之間，傳遞這種資源的某種表現層；
　　3）客戶端經過四個HTTP動詞，對服務器端資源進行操做，實現"表現層狀態轉化"

 3、restful的設計誤區

1）URI不該該有動詞，動詞應該放在HTTP協議中。

舉例來講，某個URI是/posts/show/1，其中show是動詞，這個URI就設計錯了，正確的寫法應該是/posts/1，而後用GET方法表示show。
　　若是某些動做是HTTP動詞表示不了的，你就應該把動做作成一種資源。好比網上匯款，從帳戶1向帳戶2匯款500元，錯誤的URI是：

錯誤：
    POST /accounts/1/transfer/500/to/2
正確：
    正確的寫法是把動詞transfer改爲名詞transaction，資源不能是動詞，可是能夠是一種服務：
    POST /transaction HTTP/1.1
    Host: 127.0.0.1
    from=1&to=2&amount=500.00

2）另外一個誤區，url加入版本號

錯誤：
    http://www.example.com/app/1.0/foo
    http://www.example.com/app/1.1/foo
    http://www.example.com/app/2.0/foo
正確：
    由於不一樣的版本，能夠理解成同一種資源的不一樣表現形式，因此應該採用同一個URI。
    版本號能夠在HTTP請求頭信息的Accept字段中進行區分（參見Versioning REST Services）：
    Accept: vnd.example-com.foo+json; version=1.0
    Accept: vnd.example-com.foo+json; version=1.1
    Accept: vnd.example-com.foo+json; version=2.0

 *注，雖然說restfull規範建議版本號放在請求頭而不是url裏，但事實上爲了使用方便，大多數開發者仍是喜歡把版本號放在url上，這樣容易直觀區分

4、Restful API設計指南

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

2）域名設置

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

3）版本號

應該將API的版本號放入URL。
https://api.example.com/v1/

另外一種作法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github採用這種作法。

4）url 路徑

路徑又稱"終點"（endpoint），表示API的具體網址。在RESTful架構中，每一個網址表明一種資源（resource），
因此網址中不能有動詞，只能有名詞，並且所用的名詞每每與數據庫的表格名對應。
通常來講，數據庫中的表都是同種記錄的"集合"（collection），因此API中的名詞也應該使用複數。
舉例來講，有一個API提供動物園（zoo）的信息，還包括各類動物和僱員的信息，則它的路徑應該設計成下面這樣。　　
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

5）HTTP動詞。

  經常使用的HTTP動詞有下面五個（括號裏是對應的SQL命令）。

對於資源的具體操做類型，由HTTP動詞表示。

GET（SELECT）：從服務器取出資源（一項或多項）。
POST（CREATE）：在服務器新建一個資源。
PUT（UPDATE）：在服務器更新資源（客戶端提供改變後的完整資源）。
PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）。
DELETE（DELETE）：從服務器刪除資源。

  不經常使用的HTTP動詞。

HEAD：獲取資源的元數據。
OPTIONS：獲取信息，關於資源的哪些屬性是客戶端能夠改變的。

 舉例說明

GET /zoos：列出全部動物園
POST /zoos：新建一個動物園
GET /zoos/ID：獲取某個指定動物園的信息
PUT /zoos/ID：更新某個指定動物園的信息（提供該動物園的所有信息）
PATCH /zoos/ID：更新某個指定動物園的信息（提供該動物園的部分信息）
DELETE /zoos/ID：刪除某個動物園
GET /zoos/ID/animals：列出某個指定動物園的全部動物
DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物

6）過濾信息。若是記錄數量不少，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。

常見的過濾參數
?limit=10：指定返回記錄的數量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
?sortby=name&order=asc：指定返回結果按照哪一個屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件

7）狀態碼。服務器向用戶返回的狀態碼和提示信息，常見的有如下一些（方括號中是該狀態碼對應的HTTP動詞）。

*    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 - [*]：服務器發生錯誤，用戶將沒法判斷髮出的請求是否成功。

8）錯誤處理（Error handling）若是狀態碼是4xx，就應該向用戶返回出錯信息。通常來講，返回的信息中將error做爲鍵名，出錯信息做爲鍵值便可。

{
    error: "Invalid API key"
}

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

GET   /collection：返回資源對象的列表（數組）
GET   /collection/resource：返回單個資源對象
POST  /collection：返回新生成的資源對象
PUT   /collection/resource：返回完整的資源對象
PATCH /collection/resource：返回完整的資源對象
DELETE /collection/resource：返回一個空文檔

10）Hypermedia API

RESTful API最好作到Hypermedia，即返回結果中提供連接，連向其餘API方法，使得用戶不查文檔，也知道下一步應該作什麼。
好比，當用戶向api.example.com的根目錄發出請求，會獲得這樣一個文檔。

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

上面代碼表示，文檔中有一個link屬性，用戶讀取這個屬性就知道下一步該調用什麼API了。

rel表示這個API與當前網址的關係（collection關係，並給出該collection的網址），
href表示API的路徑，title表示API的標題，type表示返回類型。
Hypermedia API的設計被稱爲HATEOAS。Github的API就是這種設計，訪問api.github.com會獲得一個全部可用API的網址列表。

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

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

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

5、Django rest framework實踐

實戰連接：http://www.cnblogs.com/alex3714/articles/7131523.html 　

文章連接：https://www.cnblogs.com/alex3714/articles/6808013.html