在很多情況下,在開發REST API(或嘗試使用這種模式)時,我們並不重視建立乾淨,可理解且可擴充套件的體系結構的重要性,但從長遠來看,隨著應用程式的增長,這將產生巨大影響。
假設現在是時候向用戶公開我們正在開發的介面了,那麼您如何確定他們瞭解您嘗試在介面中傳輸的內容呢?對使用該應用程式的使用者的理解不僅是相關的,而且對於您的團隊和將來將要使用該應用程式的人們來說也是可以理解的。從架構的開始就建立一個每個人都會尊重的基礎是至關重要的。
這些是我認為最重要的幾個方面:
1.使用HTTP方法賦予端點含義REST API鼓勵我們對應用程式的每個CRUD操作使用HTTP方法。其中,我們有以下幾種:GET,POST,PUT,DELETE和PATCH。與資源關聯的端點的名稱必須帶有與所應用的動作有關的HTTP方法。
- GET /get_cats
- POST /insert_cats
- PUT /modify_cats
- DELETE /delete_cats
+ GET /cats
+ POST /cats
+ PUT /cats
+ DELETE /cats
2.狀態程式碼必須符合我們API的結果。我們應用程式最重要的品質之一就是端點的返回與相應的狀態碼有關。這意味著一旦我們的結果成功或失敗,我們就可以以更具描述性的方式關聯我們想要傳達的資訊。
例如,如果我們獲得狀態200,則可以立即知道我們的結果是成功的;否則,如果我們獲得狀態400,則結果將失敗。
重要的是要知道現有的狀態碼,並知道我們需要在每種情況下應用它們,因為返回訊息可能會錯誤地與某些狀態碼相關聯(這很常見),這對於正常工作非常有害。應用程式,因為它會使我們的REST API的開發人員和消費者使用者感到困惑。
// Bad, we return status code
200 (Success)
// associated with an error object
{ "status": 200, "error": {...}}
// Good
{ "status": 200, "data": [...]}
3.篩選,排序和分頁支援在任何使用我們的API的應用程式中,很多情況都希望以某種方式從我們的服務中消耗更少的資源,這可能是由於效能,搜尋系統,資訊過多或僅僅是顯示我們資源中的某些特殊內容。
過濾,排序和分頁,除了擴充套件API的功能外,還有助於我們減少伺服器資源的消耗。
假設端點返回了數百萬個結果,那麼我們的伺服器會如何反應?(他肯定會哭泣並崩潰)。
· GET / cats?race = misumisu&age = 1
->過濾,檢索所有具有以下屬性的貓:種族為misumisu,年齡為1。
· GET / cats?limit = 15&offset = 0
->分頁,從0行開始返回15行。
· GET / cats?limit = 15&offset = 0
->排序,返回按名稱升序排列的行。
資源將不會總是有一個結果,一個表可能會有很多結果,即使它只有一個結果,並且我們將其放在單數形式,我們也不會保持路由名稱格式的一致性。
"一致性是成功的關鍵"
- GET /cat
- GET /cat/:id
+ GET /cats
+ GET /cats/:id
5.使用資源名稱命名端點說到一致性,如果我們知道路由負責處理資源上的操作,則必須直接用資源名稱來命名它,因此當一個人使用我們的API時,他們將瞭解他們正在使用的實體上。
例如,如果您要歸還貓,則不會將端點稱為/ dogs dog。
6.資源層次如果我們要訪問屬於資源的緊密連結的實體怎麼辦?
為了顯示這種關係,我們有兩個選擇:
· 在我們的作者端點中分層地附加文章
· 請求引數
讓我們以"作者"和"文章"的經典示例為例。
GET /authors/betoyanes/articles/create_cat_memes
GET /articles?author=betoyanes&name=create_cat_memes
這些方法是有效的,我在許多專案中都已看到它們。就個人而言,我認為使用查詢字串比擴充套件當前路徑更乾淨。應用程式擴充套件得越多,我們肯定會具有更大的層次結構,反過來,路由也會擴充套件。即使這樣,它還是根據每個人的標準,所以使用最喜歡的一個!
7.版本控制隨著我們的發展,不可避免的是要有一個穩定且確定的API版本,且沒有錯誤和防彈。假設我們部署了API,並且有多個客戶端開始使用它,那麼當您需要在資源中新增或刪除更多資料時,會發生什麼情況?您可能會在佔用我們介面的外部服務上生成錯誤。這就是為什麼對我們的應用程式具有版本控制機制至關重要的原因。
有幾種方法,但是我是版本化URI的支持者,在該版本中,我們將在端點中明確擁有路由的版本。
// URI versioning v[x] syntax
GET /v1/cats
GET /v2/dogs
8.快取快取記憶體是一種可以提高API速度和降低資源消耗的強大工具之一,其思想是不要繼續多次向您的資料庫請求相同的請求,如果它繼續獲得相同的結果。有多種服務可以幫助我們實現此係統,其中,Redis是我的最愛之一。
我們肯定聽說過實現快取功能通常會帶來成本,而且也不例外。讓我們問以下問題,資訊是動態的還是靜態的?如果是動態的,資訊多久更改一次?
重要的是要知道快取中有很長時間的資訊,這可能會導致透過長時間保留資訊而導致API的錯誤結果,建議使用較短的快取時間。
9.文件文件是我們最好的武器之一,也是許多人最討厭的武器。在這種情況下,文件化的API是必不可少的,以便使用我們的使用者可以理解我們介面的幾個重要方面,包括可訪問性,響應,請求,示例。
· 可訪問性:介面的位置和訪問許可權是最重要的品質之一,我們不希望向客戶提供how_to_use.txt。在雲上公開我們的文件,每個人都可以看到,這是我們可以做的最方便的事情。
· 響應和請求:我們提供的資訊必須考慮任何資源可能產生的所有可能結果以及如何使用它們。
· 示例:提供示例說明如何使用我們的介面非常重要,即使它是我們可以在控制檯中執行並從中獲得響應的bash指令碼。
結論請記住,我們的API是我們暴露以使用後端服務的介面,因此請牢記這一點,重要的是應用最佳的原則,以便使用和使用它的人們都喜歡。
儘管我們正在開發個人專案,但是我們需要嘗試應用我們考慮的最佳原則,以便我們在進入開發團隊或專案時可以得到實踐。