RestFramework——API設計規範

 

what's the RESTful

　　RestFramework是一個能快速爲咱們提供API接口，方便咱們編程的框架。API是後端編程人員寫的，爲了讓前端拿數據的一個接口，一般就是以url的形式存在。

　　每一個項目總有第一我的作基礎構架，這個時候就不是僅僅實現一個API就OK了，須要考慮更多的事情，包括

• • 　　統一的異常處理

  • 　　API權限

  • 　　統一的參數校驗

  • 　　緩存如何能夠作的更簡單統一

  • 　　認證

  • 　　統一的查詢過濾

  • 　　代碼分層

RestFramework能很好的幫咱們作這些事情。

瞭解RestFramework以前咱們首先要知道什麼是REST：

• REST是一種標準，restful是一種規範，根據產品需求須要定出一份方便先後端的規範，與協議（如HTTP協議）不一樣，不是全部的標準要求都須要遵循。
• REST與技術無關，表明的是一種軟件架構風格，REST是Representational State Transfer的簡稱，中文翻譯爲「表徵狀態轉移」
• REST從資源的角度類審視整個網絡，它將分佈在網絡中某個節點的資源經過URL進行標識，客戶端應用經過URL來獲取資源的表徵，得到這些表徵導致這些應用轉變狀態
• 全部的數據，不過是經過網絡獲取的仍是操做（增刪改查）的數據，都是資源，將一切數據視爲資源是REST區別與其餘架構風格的最本質屬性
• 對於REST這種面向資源的架構風格，有人提出一種全新的結構理念，即：面向資源架構（ROA：Resource Oriented Architecture）

 

API設計規範

　　首先咱們要知道，API並非必須的，若是整個項目只有你一我的或者不多的人完成，徹底能夠直接用Django的模板引擎渲染髮送到前端後直接操做。API的使用主要是爲了解決多人開發，特別是先後端分離的狀況。由於前端人員在製做頁面時必然會須要向後端要數據，可是假如先後端是分離的，就不能用Django的render了，大部分狀況前端會用ajax發送請求，後端人員則發送JSON字符串給前端，前端再反序列化後進行使用。這個時候其實咱們設計一套API出來，就能使咱們的任務輕鬆不少。因此，RestFramework就應運而生了。

　　API與用戶的通訊協議，本質上是HTTPs協議。

使用RestFramework設計API有一套規範，即RESTful，爲了避免平添與你合做開發的人的煩惱，咱們仍是要遵循這些規範。那麼到底有哪些規範呢？

1. 域名：域名上要顯示你使用了API，咱們有兩種方式
   • https://api.example.com                  方式一：將API部署在專用域名上（是官網的推薦方式，但這麼作會存在跨域問題）
   • https://example.org/api/                  方式二： 寫在路徑上，API很簡單
2. 版本：咱們的項目在開發過程當中會進行功能的添加及優化，這個時候咱們一般會爲每個版本設定一個版本號，版本號的顯示也有兩種方式
   • https://api.example.com/v1/　　     方式一： 寫在路徑上，API很簡單
   • https://v1.example.com                   方式二：將版本號部署在專用域名上（一樣會存在跨域問題， 跨域時會引起發送屢次請求）
3. 路徑：視網絡上任何東西都是資源，因此路徑均使用名詞表示（可複數）
   • https://api.example.com/v1/zoos
   • https://api.example.com/v1/animals
4. 請求方式：
   • GET      ：從服務器取出資源（一項或多項）
   • POST    ：在服務器新建一個資源
   • PUT      ：在服務器更新資源（客戶端提供改變後的完整資源——所有修改）
   • PATCH  ：在服務器更新資源（客戶端提供改變的屬性——部分修改）
   • DELETE ：從服務器刪除資源
5. 過濾：經過在URL上傳參的方式，有GET請求獲取相應的數據
   • 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：指定篩選條件
6. 狀態碼：咱們能夠經過狀態碼來判斷請求的狀態，以處理相應的請求。在狀態碼是4開頭時，應該捕捉相應錯誤並返回錯誤信息

   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 - [*]：服務器發生錯誤，用戶將沒法判斷髮出的請求是否成功。 更多看這裏：http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

   經常使用狀態碼

   {error: "Invalid API key"}#錯誤信息因用error做爲key

7. 返回結果：針對不一樣操做，服務器向用戶返回的結果應該符合如下規範。
   • GET/collection：返回資源對象的列表
   • GET/collection/resource：返回單個資源對象
   • POST/collection：返回新生成的資源對象
   • PUT/collection/resource：返回完整的資源對象
   • PATCH/collection/resource：返回完整的資源對象
   • DELETE/collection/resource：返回一個空文檔
   • 　
8. Hypermedia API：RESTful API最好作到Hypermedia，即返回結果中提供連接，連向其餘API方法，使得用戶不查文檔，也知道下一步應該作什麼。

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