如何設計出優美的Web API？

時間 2020-05-16

標籤如何設計優美 web api 欄目 HTML 简体版

原文原文鏈接

1. 概述

WEB API的應用場景很是豐富，例如：將已有系統的功能或數據開放給合做夥伴或生態圈；對外發布可嵌入到其餘網頁的微件；構建先後端分離的WEB應用；開發跨不一樣終端的移動應用；集成公司內部不一樣系統等等。在上述場景裏，你多是WEB API的使用者，也多是設計者，但你知道如何評判WEB API的優劣嗎？php

2. 評判標準

咱們能夠從三個維度來評判一個WEB API的優劣：git

易於使用：WEB API的用戶是程序仍是人？我以爲首先是人，而後是程序。爲何這麼說呢？是否採用某個WEB API的決定是人作出的，一個好的WEB API必須符合人的審美，例如：簡短易記、通俗易懂、便於輸入等。從程序角度看，WEB API應該遵循行業規範，在調用時不須要作特殊化處理，有利於複用已有的代碼或工具。
便於更改：一個WEB API發佈上線以後，免不了要根據真實用戶的反饋或者業務發展的須要作更新修改，這些更新修改必須儘可能不影響用戶。要麼提供多版本支持，要麼給用戶提供切實可行的更新策略等等。
健壯穩定：對外公開的WEB API存在被***的風險，以及沒法準確預估的訪問量等，一個好的WEB API必需要有防注入、防篡改、防重放等安全機制，還要在訪問量急劇上漲時避免服務被擊穿。

作到了上述三個方面，咱們纔有底氣將一個WEB API對外開放，接受公衆的檢驗。好的WEB API不只方便使用，還助於提高我的或企業的技術影響力，從而造成正向循環，帶來愈來愈多的業務價值。爲了設計出優美的WEB API，咱們須要瞭解與之相關的設計規範和事實標準，而且在設計開發過程當中儘可能遵循它們。github

3. 設計規範

3.1 URI

便於輸入的URI，簡短不冗餘。每一個WEB API都是一個服務，那下面反例當中的「service」就是冗餘的，並且「api」也重複出現了兩次，這種冗餘都不利於記憶和輸入：

反例：http://api.example.com/service/api/users
正例：http://api.example.com/users

容易讀懂的URI，不要隨意採用縮寫，縮寫必需要符合國際標準規範，不要憑空發明創造，例如：國家代碼定義（ISO3166）。反例中出現了兩處縮寫「sv」、「u」，在沒有附加說明的狀況下，用戶壓根不知道含義：

反例：http://api.example.com/sv/u

沒有大小寫混用的URI。HTTP協議（RFC7230）規定：除了模式（schema）和主機名之外，URI的其餘信息都要區分字母的大小寫。下述兩個反例大小寫混用，不方便記憶。

反例：http://api.example.com/Users/12345
反例：http://example.com/API/getUserName

易於修改的URI，命名存在可預見的規律。下述正例咱們能夠很容易猜想改變最後的ID就能夠訪問其餘商品的信息。

正例：http://api.example.com/v1/items/123456

不會暴露服務端架構的URI，URI只須要體現功能、數據結構和含義，無需暴露服務端如何運做的信息。這些信息對用戶來講沒有意義，還存在潛在的風險，惡意用戶或者會利用這些信息來尋找漏洞，發起對服務的。

反例：http://api.example.com/cgi-bin/get_user.php?user=100

規則統一的URI，確保採用統一的規則和風格，方便用戶記憶和使用。下述反例中第一個URI採用了查詢參數，第二個URI採用了路徑參數，這二者沒有保持一致，容易形成混亂。

反例：獲取好友信息，http://api.example.com/friends?id=100
反例：發送消息，http://api.example.com/friend/100/messages
正例：獲取好友信息，http://api.example.com/friends/100
正例：發送消息，http://api.example.com/friends/100/messages

URI最好由名詞組成。URI的全稱是統一資源定位符（Uniform Resource Identifier），用於標識資源在互聯網上的位置，相似於郵寄地址，而地址都是由名詞組成的。在名詞使用上也有一些須要注意的事項：其一，使用名詞複數形式；其二，儘可能採用多數API中使用的表示相同含義的單詞；其三，經過儘量少的單詞來表示；其四，儘量不用奇怪的縮略語等。
不使用空格及須要編碼的字符，例如在URI中使用中文等。
使用鏈接符（-）來鏈接多個單詞，推薦脊柱法：首先，URI裏的主機名（域名）容許使用連字符而禁止使用下劃線，且不區分大小寫。其次，點字符具備特殊含義，爲了與主機名的規則保持一致。

脊柱法：http://api.example.com/v1/users/12345/profile-image
蛇形法：http://api.example.com/v1/users/12345/profile_image
駝峯法：http://api.example.com/v1/users/12345/profileImage

3.2 查詢參數

許多場景下須要經過API分批次獲取數據，咱們會常常糾結采用什麼樣的查詢參數，業界有兩種經常使用的參數設計（per-page與page、limit與offset），用於標識每次獲取的數據量和起始位置。在分批次獲取數據的過程當中，數據集合中的記錄可能發生增刪改變，咱們須要注意採用相對位置或絕對位置所帶來的不一樣效果。

風格1：http://api.example.com/friends?per-page=50&page=3
風格2：http://api.example.com/friends?limit=50&offset=100

在設計過濾的參數時，業界也有一些事實標準可供參考。若是咱們指望查詢結果的特定屬性取值跟過濾參數的取值徹底相同，那過濾參數的名稱一般爲屬性名；若是咱們指望查詢結果任意屬性部分包含過濾參數的取值，那過濾參數的名稱一般爲「q」。

徹底符合：http://api.example.com/v1/users?name=ken
全文搜索：http://api.example.com/v1/users?q=ken

URI是否能夠包含動詞「search」？一般以搜索爲主的在線服務API能夠包含，除此以外建議採用名詞複數形式。經常使用英文單詞「search」和「find」都有查找的含義，但二者仍是有一些細微的差異，其中「search」用於模糊搜索，而「find」用於精準查詢。

模糊搜索：http://yboss.yahooapis.com/ysearch/web?q=ipod

某個屬性到底是做爲URI路徑的構成元素仍是做爲查詢參數呢？咱們能夠按照如下規則來判斷：若是該屬性信息能夠惟必定位資源，那麼它就適合做爲路徑構成元素，不然就做爲查詢參數；若是該屬性能夠省略，那麼它就是適合做爲查詢參數。

路徑元素：http://api.example.com/v1/users/{id}
查詢參數：http://api.example.com/v1/users?name=ken

3.3 HTTP方法

按照HTTP協議設計的本意，URI用於標識目標對象（資源），而HTTP方法則是表示操做方法。基於HTTP協議的簡單對象訪問協議SOAP逐漸被RESTful的原生HTTP協議取代，咱們也沒有必要多此一舉，最好就是吃透HTTP協議，充分利用它的特性。web

GET /v1/users/123 HTTP/1.1
Host: api.example.com

GET，獲取資源
POST，新增資源
PUT，更新已有資源
DELETE，刪除資源
PATCH，更新部分資源
HEAD，獲取資源的元信息

若是遇到上述HTTP方法沒法覆蓋的場景，那一般是資源的設計粒度太大了，咱們能夠把粗粒度的資源分解成多個細粒度的資源。在使用HTTP協議設計WEB API的專業能力上，業界將其劃分爲四個層級，LEVEL3相對較理想化，缺少實施的基礎，LEVEL2是切實可行的：json

LEVEL 0：使用HTTP
LEVEL 1：引入資源的概念
LEVEL 2：引入HTTP動詞（GET/POST/PUT/DELETE等）
LEVEL 3：引入HATEOAS概念

3.4 響應數據

經常使用的數據格式有：HTML、XML、JSON、YAML等，若是咱們的服務在響應時支持不一樣類型的數據格式，那應用在調用服務時如何得到指望格式的響應數據呢？一般咱們能夠考慮採用下述幾種指定數據格式的方法：後端

使用查詢參數的方法：

示例：https://api.example.com/v1/users?format=xml

使用擴展名的方法：

示例：https://api.example.com/v1/users.json

使用在請求首部指定媒體類型的方法，優先推薦此種方法：

GET /v1/users
Host: api.example.com
Accept: application/json

響應數據應該包含哪些信息呢？是否越多越好？亦或越少越好，僅僅包含ID？建議是按需返回，根據業務功能所需返回相應的數據。若是一個WEB API須要提供給不一樣業務場景使用，不一樣業務場景對數據屬性信息的要求不一樣，或多或少，這種狀況咱們可讓用戶來選擇響應的內容，選擇方法就是經過查詢參數指定：api

示例：http://api.example.com/v1/users/123?fields=name,age

響應數據的結構應該儘可能扁平化，不要嵌套太深，減小沒有具體含義的信息載荷，這樣既能夠壓縮報文尺寸，又能夠節省帶寬的。固然，若是層級結構更具優點，也能夠採用。緩存

3.5 出錯信息

建議經過HTTP協議首部的狀態碼來表示出錯信息，而不是再封裝一層，遵照協議規範的好處是能夠減小溝通的成本，也能夠利用許多成熟的軟硬件產品來處理異常出錯信息。HTTP協議定了了五種類型的狀態碼：安全

1XX：消息
2XX：成功
3XX：重定向
4XX：客戶端緣由引發的錯誤
5XX：服務器端緣由引發的錯誤

咱們須要每種狀態碼的使用場景，確保正確使用狀態碼。除此以外，服務還須要向客戶端返回詳細的出錯信息，咱們一般能夠採用下述兩種方法來傳遞詳細的出錯信息：服務器

方法1：定義私有的首部，將其填入響應消息的首部。
方法2：將詳細的出錯信息放入消息體。

3.6 版本管理

隨着業務的發展，每一個發佈上線的WEB API都存在更新修改的可能，那就須要引入版本管理的機制。業界有三種常見的標註WEB API版本的方法：

在URI中嵌入版本編號：

示例：http://api.linkedin.com/v1/people

在查詢字符串里加入版本信息：

示例：http://api.example.com/users/123?v=2

經過媒體類型來指定版本信息

Accept: application/vnd.github.v3+json
Content-Type: application/vnd.github.v3+json

一樣，版本編號也存在業界規範：語義化版本控制（Semantic Versioning）規範，網站地址：http://semver.org。版本編號由點號鏈接的3個數字組成，例如：1.2.3，分別表示主版本編號、次版本編號、補丁版本編號，版本編號的增長遵循下述規則：

在對軟件進行不向下兼容的變動時，增長主版本編號；
在對軟件進行向下兼容的變動或廢除某些特定的功能時，增長次版本編號；
若是軟件的API沒有發生變動，只是修正了部分bug，則增長補丁版本編號。

按照版本編號增加的規則，WEB API的版本編號只須要標註主版本編號就能夠了，由於次版本編號、補丁版本編號的增長均可以作到向下兼容，不會影響用戶使用，惟有主版本編號增長才須要用戶更新升級。除了標註版本信息以外，咱們在對外發布WEB API時還須要設計好版本變動的策略，例如：老版本提供多久的過渡期、同時兼容多少個版本、特定版本的終止日期等等。

4. 總結

何爲優美？就是符合大衆審美的，對於WEB API來講，就是符合標準規範的，這有利於下降用戶學習和使用的成本，便於交流，不存在隱沒成本。一般，業界存在的標準規範和事實標準都是通過實踐篩選出來的，從遵循模仿開始，而後再找機會創新，而不是一上來就重複發明輪子。

WEB API設計領域的標準規範就是URI、HTTP等，咱們要最大程度地利用這些協議規範，讓每一個WEB API都是用戶友好（易於使用）、技術友好（支持緩存、易於更改）的。除此以外，咱們還須要考慮WEB API的健壯性，下一次咱們再來談一談如何設計健壯的WEB API，歡迎你們找我討論交流相關話題。

今天先分享到這裏，堅持原創不易，若是你以爲有價值，麻煩動動手指點下文「