怎樣設(shè)計符合規(guī)范的的Web API？其實要解決這個問題也不難，為此小編總結(jié)了這篇文章，下面我們一起來看看設(shè)計出符合規(guī)范的的Web API的設(shè)計方案。

成都創(chuàng)新互聯(lián)公司服務(wù)項目包括梨樹網(wǎng)站建設(shè)、梨樹網(wǎng)站制作、梨樹網(wǎng)頁制作以及梨樹網(wǎng)絡(luò)營銷策劃等。多年來，我們專注于互聯(lián)網(wǎng)行業(yè)，利用自身積累的技術(shù)優(yōu)勢、行業(yè)經(jīng)驗、深度合作伙伴關(guān)系等，向廣大中小型企業(yè)、政府機構(gòu)等提供互聯(lián)網(wǎng)行業(yè)的解決方案，梨樹網(wǎng)站推廣取得了明顯的社會效益與經(jīng)濟效益。目前，我們服務(wù)的客戶以成都為中心已經(jīng)輻射到梨樹省份的部分城市，未來相信會繼續(xù)擴大服務(wù)區(qū)域并繼續(xù)獲得客戶的支持與信任！

1. 概述

WEB API的應(yīng)用場景非常豐富，例如：將已有系統(tǒng)的功能或數(shù)據(jù)開放給合作伙伴或生態(tài)圈；對外發(fā)布可嵌入到其他網(wǎng)頁的微件；構(gòu)建前后端分離的WEB應(yīng)用；開發(fā)跨不同終端的移動應(yīng)用；集成公司內(nèi)部不同系統(tǒng)等等。

2. 評判標(biāo)準(zhǔn)

我們可以從三個維度來評判一個WEB API的優(yōu)劣：

• 易于使用：WEB API的用戶是程序還是人？我覺得首先是人，然后是程序。為什么這么說呢？是否采用某個WEB API的決定是人做出的，一個好的WEB API必須符合人的審美，例如：簡短易記、通俗易懂、便于輸入等。從程序角度看，WEB API應(yīng)該遵循行業(yè)規(guī)范，在調(diào)用時不需要做特殊化處理，有利于復(fù)用已有的代碼或工具。
• 便于更改：一個WEB API發(fā)布上線之后，免不了要根據(jù)真實用戶的反饋或者業(yè)務(wù)發(fā)展的需要做更新修改，這些更新修改必須盡量不影響用戶。要么提供多版本支持，要么給用戶提供切實可行的更新策略等等。
• 健壯穩(wěn)定：對外公開的WEB API存在被***的風(fēng)險，以及無法準(zhǔn)確預(yù)估的訪問量等，一個好的WEB API必須要有防注入、防篡改、防重放等安全機制，還要在訪問量急劇上漲時避免服務(wù)被擊穿。

做到了上述三個方面，我們才有底氣將一個WEB API對外開放，接受公眾的檢驗。好的WEB API不僅方便使用，還助于提升個人或企業(yè)的技術(shù)影響力，從而形成正向循環(huán)，帶來越來越多的業(yè)務(wù)價值。為了設(shè)計出優(yōu)美的WEB API，我們需要了解與之相關(guān)的設(shè)計規(guī)范和事實標(biāo)準(zhǔn)，并且在設(shè)計開發(fā)過程中盡量遵循它們。

3. 設(shè)計規(guī)范

3.1 URI

• 便于輸入的URI，簡短不冗余。每個WEB API都是一個服務(wù)，那下面反例當(dāng)中的“service”就是冗余的，而且“api”也重復(fù)出現(xiàn)了兩次，這種冗余都不利于記憶和輸入：

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

• 容易讀懂的URI，不要隨意采用縮寫，縮寫必須要符合國際標(biāo)準(zhǔn)規(guī)范，不要憑空發(fā)明創(chuàng)造，例如：國家代碼定義（ISO3166）。反例中出現(xiàn)了兩處縮寫“sv”、“u”，在沒有附加說明的情況下，用戶壓根不知道含義：

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

• 沒有大小寫混用的URI。HTTP協(xié)議（RFC7230）規(guī)定：除了模式（schema）和主機名以外，URI的其他信息都要區(qū)分字母的大小寫。下述兩個反例大小寫混用，不方便記憶。

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

• 易于修改的URI，命名存在可預(yù)見的規(guī)律。下述正例我們可以很容易猜測改變最后的ID就可以訪問其他商品的信息。

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

• 不會暴露服務(wù)端架構(gòu)的URI，URI只需要體現(xiàn)功能、數(shù)據(jù)結(jié)構(gòu)和含義，無需暴露服務(wù)端如何運作的信息。這些信息對用戶來說沒有意義，還存在潛在的風(fēng)險，惡意用戶或者會利用這些信息來尋找漏洞，發(fā)起對服務(wù)的。

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

• 規(guī)則統(tǒng)一的URI，確保采用統(tǒng)一的規(guī)則和風(fēng)格，方便用戶記憶和使用。下述反例中第一個URI采用了查詢參數(shù)，第二個URI采用了路徑參數(shù)，這兩者沒有保持一致，容易造成混亂。

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

• URI最好由名詞組成。URI的全稱是統(tǒng)一資源定位符（Uniform Resource Identifier），用于標(biāo)識資源在互聯(lián)網(wǎng)上的位置，類似于郵寄地址，而地址都是由名詞組成的。在名詞使用上也有一些需要注意的事項：其一，使用名詞復(fù)數(shù)形式；其二，盡量采用多數(shù)API中使用的表示相同含義的單詞；其三，通過盡可能少的單詞來表示；其四，盡可能不用奇怪的縮略語等。
• 不使用空格及需要編碼的字符，例如在URI中使用中文等。
• 使用連接符（-）來連接多個單詞，推薦脊柱法：首先，URI里的主機名（域名）允許使用連字符而禁止使用下劃線，且不區(qū)分大小寫。其次，點字符具有特殊含義，為了與主機名的規(guī)則保持一致。

脊柱法：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 查詢參數(shù)

• 許多場景下需要通過API分批次獲取數(shù)據(jù)，我們會經(jīng)常糾結(jié)采用什么樣的查詢參數(shù)，業(yè)界有兩種常用的參數(shù)設(shè)計（per-page與page、limit與offset），用于標(biāo)識每次獲取的數(shù)據(jù)量和起始位置。在分批次獲取數(shù)據(jù)的過程中，數(shù)據(jù)集合中的記錄可能發(fā)生增刪改變，我們需要注意采用相對位置或絕對位置所帶來的不同效果。

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

• 在設(shè)計過濾的參數(shù)時，業(yè)界也有一些事實標(biāo)準(zhǔn)可供參考。如果我們期望查詢結(jié)果的特定屬性取值跟過濾參數(shù)的取值完全相同，那過濾參數(shù)的名稱通常為屬性名；如果我們期望查詢結(jié)果任意屬性部分包含過濾參數(shù)的取值，那過濾參數(shù)的名稱通常為“q”。

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

• URI是否可以包含動詞“search”？通常以搜索為主的在線服務(wù)API可以包含，除此之外建議采用名詞復(fù)數(shù)形式。常用英文單詞“search”和“find”都有查找的含義，但兩者還是有一些細微的差別，其中“search”用于模糊搜索，而“find”用于精準(zhǔn)查詢。

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

• 某個屬性究竟是作為URI路徑的構(gòu)成元素還是作為查詢參數(shù)呢？我們可以按照以下規(guī)則來判斷：如果該屬性信息可以唯一定位資源，那么它就適合作為路徑構(gòu)成元素，否則就作為查詢參數(shù)；如果該屬性可以省略，那么它就是適合作為查詢參數(shù)。

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

3.3 HTTP方法

按照HTTP協(xié)議設(shè)計的本意，URI用于標(biāo)識目標(biāo)對象（資源），而HTTP方法則是表示操作方法。基于HTTP協(xié)議的簡單對象訪問協(xié)議SOAP逐漸被RESTful的原生HTTP協(xié)議取代，我們也沒有必要畫蛇添足，最好就是吃透HTTP協(xié)議，充分利用它的特性。

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

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

如果遇到上述HTTP方法無法覆蓋的場景，那通常是資源的設(shè)計粒度太大了，我們可以把粗粒度的資源分解成多個細粒度的資源。在使用HTTP協(xié)議設(shè)計WEB API的專業(yè)能力上，業(yè)界將其劃分為四個層級，LEVEL3相對較理想化，缺乏實施的基礎(chǔ)，LEVEL2是切實可行的：

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

3.4 響應(yīng)數(shù)據(jù)

常用的數(shù)據(jù)格式有：HTML、XML、JSON、YAML等，如果我們的服務(wù)在響應(yīng)時支持不同類型的數(shù)據(jù)格式，那應(yīng)用在調(diào)用服務(wù)時如何獲得期望格式的響應(yīng)數(shù)據(jù)呢？通常我們可以考慮采用下述幾種指定數(shù)據(jù)格式的方法：

• 使用查詢參數(shù)的方法：

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

• 使用擴展名的方法：

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

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

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

響應(yīng)數(shù)據(jù)應(yīng)該包含哪些信息呢？是否越多越好？亦或越少越好，僅僅包含ID？建議是按需返回，根據(jù)業(yè)務(wù)功能所需返回相應(yīng)的數(shù)據(jù)。如果一個WEB API需要提供給不同業(yè)務(wù)場景使用，不同業(yè)務(wù)場景對數(shù)據(jù)屬性信息的要求不同，或多或少，這種情況我們可以讓用戶來選擇響應(yīng)的內(nèi)容，選擇方法就是通過查詢參數(shù)指定：

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

響應(yīng)數(shù)據(jù)的結(jié)構(gòu)應(yīng)該盡量扁平化，不要嵌套太深，減少沒有具體含義的信息載荷，這樣既可以壓縮報文尺寸，又可以節(jié)省帶寬的。當(dāng)然，如果層級結(jié)構(gòu)更具優(yōu)勢，也可以采用。

3.5 出錯信息

建議通過HTTP協(xié)議首部的狀態(tài)碼來表示出錯信息，而不是再封裝一層，遵守協(xié)議規(guī)范的好處是可以減少溝通的成本，也可以利用許多成熟的軟硬件產(chǎn)品來處理異常出錯信息。HTTP協(xié)議定了了五種類型的狀態(tài)碼：

• 1XX：消息
• 2XX：成功
• 3XX：重定向
• 4XX：客戶端原因引起的錯誤
• 5XX：服務(wù)器端原因引起的錯誤

我們需要每種狀態(tài)碼的使用場景，確保正確使用狀態(tài)碼。除此之外，服務(wù)還需要向客戶端返回詳細的出錯信息，我們通常可以采用下述兩種方法來傳遞詳細的出錯信息：

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

3.6 版本管理

隨著業(yè)務(wù)的發(fā)展，每個發(fā)布上線的WEB API都存在更新修改的可能，那就需要引入版本管理的機制。業(yè)界有三種常見的標(biāo)注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

同樣，版本編號也存在業(yè)界規(guī)范：語義化版本控制（Semantic Versioning）規(guī)范，網(wǎng)站地址：http://semver.org。版本編號由點號連接的3個數(shù)字組成，例如：1.2.3，分別表示主版本編號、次版本編號、補丁版本編號，版本編號的增加遵循下述規(guī)則：

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

按照版本編號增長的規(guī)則，WEB API的版本編號只需要標(biāo)注主版本編號就可以了，因為次版本編號、補丁版本編號的增加都可以做到向下兼容，不會影響用戶使用，唯有主版本編號增加才需要用戶更新升級。除了標(biāo)注版本信息之外，我們在對外發(fā)布WEB API時還需要設(shè)計好版本變更的策略，例如：老版本提供多久的過渡期、同時兼容多少個版本、特定版本的終止日期等等。

關(guān)于Web API的設(shè)計方案就分享到這里了，希望以上內(nèi)容可以對大家有一定的幫助，可以學(xué)到更多知識。如果覺得文章不錯，可以把它分享出去讓更多的人看到。

另外有需要云服務(wù)器可以了解下創(chuàng)新互聯(lián)cdcxhl.cn，海內(nèi)外云服務(wù)器15元起步，三天無理由+7*72小時售后在線，公司持有idc許可證，提供“云服務(wù)器、裸金屬服務(wù)器、高防服務(wù)器、香港服務(wù)器、美國服務(wù)器、虛擬主機、免備案服務(wù)器”等云主機租用服務(wù)以及企業(yè)上云的綜合解決方案，具有“安全穩(wěn)定、簡單易用、服務(wù)可用性高、性價比高”等特點與優(yōu)勢，專為企業(yè)上云打造定制，能夠滿足用戶豐富、多元化的應(yīng)用場景需求。

網(wǎng)頁名稱：怎樣設(shè)計符合規(guī)范的的WebAPI？-創(chuàng)新互聯(lián)
網(wǎng)站鏈接：http://www.rwnh.cn/article40/dcidho.html

成都網(wǎng)站建設(shè)公司_創(chuàng)新互聯(lián)，為您提供關(guān)鍵詞優(yōu)化、網(wǎng)站設(shè)計公司、營銷型網(wǎng)站建設(shè)、標(biāo)簽優(yōu)化、響應(yīng)式網(wǎng)站、電子商務(wù)

廣告

聲明：本網(wǎng)站發(fā)布的內(nèi)容（圖片、視頻和文字）以用戶投稿、用戶轉(zhuǎn)載內(nèi)容為主，如果涉及侵權(quán)請盡快告知，我們將會在第一時間刪除。文章觀點不代表本網(wǎng)站立場，如需處理請聯(lián)系客服。電話：028-86922220；郵箱：631063699@qq.com。內(nèi)容未經(jīng)允許不得轉(zhuǎn)載，或轉(zhuǎn)載時需注明來源： 創(chuàng)新互聯(lián)