您好,登錄后才能下訂單哦!
怎樣設計符合規(guī)范的的Web API?其實要解決這個問題也不難,為此小編總結了這篇文章,下面我們一起來看看設計出符合規(guī)范的的Web API的設計方案。
WEB API的應用場景非常豐富,例如:將已有系統(tǒng)的功能或數(shù)據(jù)開放給合作伙伴或生態(tài)圈;對外發(fā)布可嵌入到其他網(wǎng)頁的微件;構建前后端分離的WEB應用;開發(fā)跨不同終端的移動應用;集成公司內(nèi)部不同系統(tǒng)等等。
我們可以從三個維度來評判一個WEB API的優(yōu)劣:
做到了上述三個方面,我們才有底氣將一個WEB API對外開放,接受公眾的檢驗。好的WEB API不僅方便使用,還助于提升個人或企業(yè)的技術影響力,從而形成正向循環(huán),帶來越來越多的業(yè)務價值。為了設計出優(yōu)美的WEB API,我們需要了解與之相關的設計規(guī)范和事實標準,并且在設計開發(fā)過程中盡量遵循它們。
反例:http://api.example.com/service/api/users
正例:http://api.example.com/users
反例:http://api.example.com/sv/u
反例:http://api.example.com/Users/12345
反例:http://example.com/API/getUserName
正例:http://api.example.com/v1/items/123456
反例:http://api.example.com/cgi-bin/get_user.php?user=100
反例:獲取好友信息,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
脊柱法: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
風格1:http://api.example.com/friends?per-page=50&page=3
風格2:http://api.example.com/friends?limit=50&offset=100
完全符合:http://api.example.com/v1/users?name=ken
全文搜索:http://api.example.com/v1/users?q=ken
模糊搜索:http://yboss.yahooapis.com/ysearch/web?q=ipod
路徑元素:http://api.example.com/v1/users/{id}
查詢參數(shù):http://api.example.com/v1/users?name=ken
按照HTTP協(xié)議設計的本意,URI用于標識目標對象(資源),而HTTP方法則是表示操作方法?;贖TTP協(xié)議的簡單對象訪問協(xié)議SOAP逐漸被RESTful的原生HTTP協(xié)議取代,我們也沒有必要畫蛇添足,最好就是吃透HTTP協(xié)議,充分利用它的特性。
GET /v1/users/123 HTTP/1.1
Host: api.example.com
如果遇到上述HTTP方法無法覆蓋的場景,那通常是資源的設計粒度太大了,我們可以把粗粒度的資源分解成多個細粒度的資源。在使用HTTP協(xié)議設計WEB API的專業(yè)能力上,業(yè)界將其劃分為四個層級,LEVEL3相對較理想化,缺乏實施的基礎,LEVEL2是切實可行的:
常用的數(shù)據(jù)格式有:HTML、XML、JSON、YAML等,如果我們的服務在響應時支持不同類型的數(shù)據(jù)格式,那應用在調(diào)用服務時如何獲得期望格式的響應數(shù)據(jù)呢?通常我們可以考慮采用下述幾種指定數(shù)據(jù)格式的方法:
示例: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
響應數(shù)據(jù)應該包含哪些信息呢?是否越多越好?亦或越少越好,僅僅包含ID?建議是按需返回,根據(jù)業(yè)務功能所需返回相應的數(shù)據(jù)。如果一個WEB API需要提供給不同業(yè)務場景使用,不同業(yè)務場景對數(shù)據(jù)屬性信息的要求不同,或多或少,這種情況我們可以讓用戶來選擇響應的內(nèi)容,選擇方法就是通過查詢參數(shù)指定:
示例:http://api.example.com/v1/users/123?fields=name,age
響應數(shù)據(jù)的結構應該盡量扁平化,不要嵌套太深,減少沒有具體含義的信息載荷,這樣既可以壓縮報文尺寸,又可以節(jié)省帶寬的。當然,如果層級結構更具優(yōu)勢,也可以采用。
建議通過HTTP協(xié)議首部的狀態(tài)碼來表示出錯信息,而不是再封裝一層,遵守協(xié)議規(guī)范的好處是可以減少溝通的成本,也可以利用許多成熟的軟硬件產(chǎn)品來處理異常出錯信息。HTTP協(xié)議定了了五種類型的狀態(tài)碼:
我們需要每種狀態(tài)碼的使用場景,確保正確使用狀態(tài)碼。除此之外,服務還需要向客戶端返回詳細的出錯信息,我們通??梢圆捎孟率鰞煞N方法來傳遞詳細的出錯信息:
隨著業(yè)務的發(fā)展,每個發(fā)布上線的WEB API都存在更新修改的可能,那就需要引入版本管理的機制。業(yè)界有三種常見的標注WEB API版本的方法:
示例: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ī)則:
按照版本編號增長的規(guī)則,WEB API的版本編號只需要標注主版本編號就可以了,因為次版本編號、補丁版本編號的增加都可以做到向下兼容,不會影響用戶使用,唯有主版本編號增加才需要用戶更新升級。除了標注版本信息之外,我們在對外發(fā)布WEB API時還需要設計好版本變更的策略,例如:老版本提供多久的過渡期、同時兼容多少個版本、特定版本的終止日期等等。
關于Web API的設計方案就分享到這里了,希望以上內(nèi)容可以對大家有一定的幫助,可以學到更多知識。如果覺得文章不錯,可以把它分享出去讓更多的人看到。
免責聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉載和分享為主,文章觀點不代表本網(wǎng)站立場,如果涉及侵權請聯(lián)系站長郵箱:is@yisu.com進行舉報,并提供相關證據(jù),一經(jīng)查實,將立刻刪除涉嫌侵權內(nèi)容。