如何設計出優美的Web API?

来源:https://www.cnblogs.com/itlaobingge/archive/2019/12/24/12089657.html
-Advertisement-
Play Games

WEB API的應用場景非常豐富,例如:將已有系統的功能或數據開放給合作伙伴或生態圈;對外發佈可嵌入到其他網頁的微件;構建前後端分離的WEB應用;開發跨不同終端的移動應用;集成公司內部不同系統等等。在上述場景里,你可能是WEB API的使用者,也可能是設計者,但你知道如何評判WEB API的優劣嗎? ...


  • 概述

WEB API的應用場景非常豐富,例如:將已有系統的功能或數據開放給合作伙伴或生態圈;對外發佈可嵌入到其他網頁的微件;構建前後端分離的WEB應用;開發跨不同終端的移動應用;集成公司內部不同系統等等。在上述場景里,你可能是WEB API的使用者,也可能是設計者,但你知道如何評判WEB API的優劣嗎?

  • 評判標準

我們可以從三個維度來評判一個WEB API的優劣:

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

做到了上述三個方面,我們才有底氣將一個WEB API對外開放,接受公眾的檢驗。好的WEB API不僅方便使用,還助於提升個人或企業的技術影響力,從而形成正向迴圈,帶來越來越多的業務價值。為了設計出優美的WEB API,我們需要瞭解與之相關的設計規範和事實標準,並且在設計開發過程中儘量遵循它們。

  • 設計規範

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

查詢參數

  • 許多場景下需要通過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

HTTP方法

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

GET /v1/users/123 HTTP/1.1
Host: api.example.com
  • GET,獲取資源
  • POST,新增資源
  • PUT,更新已有資源
  • DELETE,刪除資源
  • PATCH,更新部分資源
  • HEAD,獲取資源的元信息

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

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

響應數據

常用的數據格式有: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需要提供給不同業務場景使用,不同業務場景對數據屬性信息的要求不同,或多或少,這種情況我們可以讓用戶來選擇響應的內容,選擇方法就是通過查詢參數指定:

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

響應數據的結構應該儘量扁平化,不要嵌套太深,減少沒有具體含義的信息載荷,這樣既可以壓縮報文尺寸,又可以節省帶寬的。當然,如果層級結構更具優勢,也可以採用。

出錯信息

建議通過HTTP協議首部的狀態碼來表示出錯信息,而不是再封裝一層,遵守協議規範的好處是可以減少溝通的成本,也可以利用許多成熟的軟硬體產品來處理異常出錯信息。HTTP協議定了了五種類型的狀態碼:

  • 1XX:消息
  • 2XX:成功
  • 3XX:重定向
  • 4XX:客戶端原因引起的錯誤
  • 5XX:伺服器端原因引起的錯誤

我們需要每種狀態碼的使用場景,確保正確使用狀態碼。除此之外,服務還需要向客戶端返回詳細的出錯信息,我們通常可以採用下述兩種方法來傳遞詳細的出錯信息:

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

版本管理

隨著業務的發展,每個發佈上線的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)規範,網站地址:semver.org。版本編號由點號連接的3個數字組成,例如:1.2.3,分別表示主版本編號、次版本編號、補丁版本編號,版本編號的增加遵循下述規則:

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

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

  • 總結

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

WEB API設計領域的標準規範就是URI、HTTP等,我們要最大程度地利用這些協議規範,讓每個WEB API都是用戶友好(易於使用)、技術友好(支持緩存、易於更改)的。除此之外,我們還需要考慮WEB API的健壯性,下一次我們再來談一談如何設計健壯的WEB API,歡迎大家找我討論交流相關話題。今天先分享到這裡,如果你覺得有價值,麻煩動動手指點下文 「 推薦 」按鈕,讓更多小伙伴可以看到,我也會更加有動力堅持分享。另外,老兵哥我後續還會分享職業規劃、應聘面試、技能提升、影響力打造等經驗,歡迎 關註 本專欄或歪信公主號 「 IT老兵哥 

微信公眾號「 IT老兵哥 」

關註「 IT老兵哥 」,賦能程式人生!

  • 近期職涯類熱門文章:
  1. “花式”裁員套路深,你知道嗎?
  2. 遭遇裁員,如何渡過心理危機?
  3. 如何在寒冬中找到好工作?
  4. 2C 還是 2B,跟找工作有什麼關係?
  5. 大公司 vs 小公司,你會選哪個?
  6. 記住這一點,不怕找不到好工作!
  7. 跳槽,跳還是不跳,該怎麼跳?
  8. 程式員“求包養”攻略揭秘
  9. 很努力了,為什麼我還在原地踏步?

 

  • 近期技術類熱門文章:
  1. 程式員必須懂的架構入門課
  2. 從程式員到架構師,有捷徑嗎?
  3. 圖解 Spring:HTTP 請求的處理流程與機制【1】
  4. 圖解 Spring:HTTP 請求的處理流程與機制【2】
  5. 圖解 Spring:HTTP 請求的處理流程與機制【3】
  6. 圖解 Spring:HTTP 請求的處理流程與機制【4】
  7. 圖解 Spring:HTTP 請求的處理流程與機制【5】
  8. 如何正確使用 Spring Cloud?【上】
  9. 如何正確使用 Spring Cloud?【中】
  10. 如何正確使用 Spring Cloud?【下】
  11. Spring 核心技術與產品理念剖析【上】
  12. Spring 核心技術與產品理念剖析【下】

您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 為什麼我們要學習Node.js? 1. 認為: Node.js就學習一周,時間比較短,不重要 將來工作我後端又不用Node.js做,我們又java/python/php/c,為什麼要在意它 Node.js接下來項目中又不用,不用好好學,不用在意 2. 重要性? Node.js可以說是對js功能的擴展 ...
  • 1 <input type="date" id="date_info" placeholder="請輸入時間"/> 2 3 ...... 4 5 <script> 6 $(document).ready(function () { 7 var time = new Date(); 8 var day ...
  • 1.側邊欄划出一個信息框 通常滑鼠浮動側邊欄都會划出一個信息框,每個信息框距離側邊欄的距離是相等的,所以處理此問題的方法就是 量取信息框距離側邊欄的距離,信息框設置絕對定位,父元素設置相對定位之後,信息框就會相對於父元素的相對定位進行絕對定位,取父元素的width:100%,然後加上距離信息框距離側 ...
  • 對於更簡單的Ajax調用,XMLHttpRequest是低級別的,更複雜的,並且你需要封裝函數。不幸的是,一旦你開始考慮超時,中止調用和錯誤捕獲的複雜性,Fetch也會如此。 ...
  • 首先用一個例子指出來constructor存在形式。 由上面的代碼我們總結出結論1:上面的代碼在控制台可以看出constructor是指向構造器Fruit的引用。 這個地方就有點奇怪了。這個constructor到底指向的是那個實例的構造器? 根據上面的代碼總結出結論2:constructor指向的 ...
  • 導讀 篇幅較長,乾貨十足,閱讀需要花點時間,全部手打出來的字,難免出現錯別字,敬請諒解。珍惜原創,轉載請註明出處,謝謝~! NoSql介紹與Redis介紹 什麼是Redis? Redis是用C語言開發的一個開源的高性能鍵值對(key-value)記憶體資料庫。 它提供五種數據類型來存儲值:字元串類型、 ...
  • 2019/12/24 | 在校大二上學期 | 太原科技大學 初學java後,我們會發現java難點不在於Java語法難學,而是把我們掛在瞭如何設計類的“弔繩”上了。這恰恰也是小白與入職多年的程式員的的差距之一。所以今天來分享一下我的觀點: 那麼如何設計類呢?有沒有遵循的原則可言呢?答案呢,就是下麵的 ...
  • 什麼是NServiceBus?NServiceBus 是一個用於構建企業級 .NET系統的開源通訊框架。它在消息發佈/訂閱支持、工作流集成和高度可擴展性等方面表現優異,因此是很多分散式系統基礎平臺的理想選擇。它能夠幫助開發人員在搭建企業.NET系統時避免很多典型的常見問題。同時,該框架也提供了一些可 ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發(一):使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說,近來想嘗試開發一款安卓APP,考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP,畢竟是使用Visual Studio開發工具,使用起來也比較的順手,結合微軟官方的教程進行了安卓 ...
  • 前言 QuestPDF 是一個開源 .NET 庫,用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫,它徹底改變了我們生成 PDF 文檔的方 ...
  • 項目地址 項目後端地址: https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址: ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址: http://tree ...
  • 話不多說,直接開乾 一.下載 1.官方鏈接下載: https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe,運行開始下載SQL server; 二. ...
  • 前言 隨著物聯網(IoT)技術的迅猛發展,MQTT(消息隊列遙測傳輸)協議憑藉其輕量級和高效性,已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫,為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog支持多種接收器用於日誌存儲,增強器用於添加屬性,LogContext管理動態屬性,支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項,適用於不同需求。 ...
  • 目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據,爬取信息時需要模擬瀏覽器行為,否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下: 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • 1.前言 什麼是熱更新 游戲或者軟體更新時,無需重新下載客戶端進行安裝,而是在應用程式啟動的情況下,在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR,Xlua,ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles,Addressable, ...
  • 本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺,其實像阿裡雲,騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後,它會送 ...
  • 通過以下方式可以高效,並保證數據同步的可靠性 1.API設計 使用RESTful設計,確保API端點明確,並使用適當的HTTP方法(如POST用於創建,PUT用於更新)。 設計清晰的請求和響應模型,以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證,確保接收到的數據符合預期格 ...