一文詳解 API 設計最佳實踐
點擊下方“IT牧場”，選擇“設為星標”
來源：codeburst.io/best-practices-
api-design-61d4697d17ff
前言 為什么要使用 API？ 數(shù)據(jù)建模與結(jié)構(gòu)化 編寫面向資源的 API RESTful 接口 API 版本控制 了解主要和次要更新 分頁
前言
良好設計的API = 快樂的程序員 ??。
應用程序接口（API）是一種接口，它讓應用程序可以輕松地使用另一個應用程序的數(shù)據(jù)和資源，API 對于一個產(chǎn)品或公司的成功至關(guān)重要。
如果沒有 API，你大部分喜歡的軟件今天就不會存在。例如，Google Maps API 可以讓你在 app 或 Web 應用中使用 Google Maps。如果沒有它，你將不得不設計和開發(fā)自己的地圖數(shù)據(jù)庫。這樣的話，在地圖上顯示一個位置需要花費多少時間？
推薦下自己做的 Spring Boot 的實戰(zhàn)項目：
https://github.com/YunaiV/ruoyi-vue-pro
為什么要使用 API？
API 可以讓外部應用訪問您的資源 API 擴展了應用程序的功能 API 允許開發(fā)者重用應用邏輯 API 是獨立于平臺的，它們傳遞數(shù)據(jù)不受請求平臺的影響
在大多數(shù)實際場景中，數(shù)據(jù)模型 已經(jīng)存在，但由于我們將討論 API 設計最佳實踐，我將從頭開始說起。
推薦下自己做的 Spring Cloud 的實戰(zhàn)項目：
https://github.com/YunaiV/onemall
數(shù)據(jù)建模與結(jié)構(gòu)化
以 API 為中心對您的數(shù)據(jù)進行建模，是設計易于創(chuàng)建、維護和更新 API 的第一步
在設計 API 時，盡量考慮使用通用的術(shù)語，而不是使用內(nèi)部的復雜業(yè)務術(shù)語，因為這些術(shù)語在公司外可能不為人所知。你的 API 可能會對外開放，以允許外部開發(fā)人員使用你的 API 開發(fā)他們自己的應用。通過使用通用術(shù)語，你可以確保使用 API 的開發(fā)人員易于了解你的 API，并能快速上手。
假設到你正在建立一個門戶網(wǎng)站，讓用戶點評不同作者的書籍。你的公司可能會使用特定的術(shù)語，如創(chuàng)作者、創(chuàng)作、系列等來指代圖書作者、書籍和系列。但為了簡單起見，并方便外部應用開發(fā)者使用你的 API，使用通用的概念而不是公司特定的術(shù)語來創(chuàng)建 API 路徑。
https://api.domain.com/authors
?https://api.domain.com/authors/{id}/books
這有助于新的開發(fā)人員快速了解你的 API 是什么，以及如何遍歷你的數(shù)據(jù)模型。
編寫面向資源的 API
應用程序需要訪問你的資源。維護一個資源層次結(jié)構(gòu)可以幫助你更好地構(gòu)建 API。資源層次結(jié)構(gòu)是指路徑中的每個節(jié)點，它由一個集合或一個資源組成。
資源可以是一個單一的數(shù)據(jù)，例如，上面例子中的作者簡介。
集合是指一個資源的集合，在我們的例子中，它可以是一個作者所寫的書的列表。
合適的資源層次結(jié)構(gòu)可以是：
Base?Path?->?作者?(集合)?->?profile?(資源)
Base?Path?->?作者?(集合)?->?書?(集合)?->?書?(資源)
層次結(jié)構(gòu)需要保持一致，以確保開發(fā)人員在將其應用程序接入 API 時遇到的問題最少。
為了保持簡單性和一致性，這里有一些指導原則可以幫助你：
命名集合和資源時使用美式英語（例如：color 而不是 colour） 避免拼寫錯誤 使用更簡單、更常用的詞來保持清晰，例如 delete 而不是 remove 如果你使用的資源與其他 API 使用的資源相同，請使用相同的術(shù)語以保持一致。 對集合使用復數(shù)形式（例如：authors、books 等）。
RESTful 接口
HTTP 形式的 API 最廣泛接受的標準是 REST(Representational State Transfer)。它基本上意味著每個 URL 代表一個對象。
API 目的可以是以下之一：
創(chuàng)建數(shù)據(jù) Create 讀取數(shù)據(jù) Read 更新數(shù)據(jù) Update 刪除數(shù)據(jù) Delete
CRUD！猜對了!
API 通過使用一組 HTTP 命令來處理，這些命令定義了請求的性質(zhì)和它應該做什么。
GET 從 API 中檢索數(shù)據(jù)。它要求從 API 中獲取數(shù)據(jù)的表示。GET請求可以包含查詢參數(shù)，以過濾從API接收的結(jié)果。
POST 向 API 提交一條記錄，該記錄將在數(shù)據(jù)庫中創(chuàng)建一個資源。
PUT 一般用于更新服務器上的現(xiàn)有資源。
DELETE 從服務器上刪除一個資源。
API 版本控制
應用程序和 API 的生命周期越長，應用和 API 對用戶的承諾就越大。在某個時間點上，你的 API 將需要修改，因為你無法預見隨著需求和業(yè)務政策而發(fā)生的變化。
因此需要對 API 進行更改。但是 API 可能已經(jīng)有一個或多個開發(fā)者在使用了，所以，重要的是，你所做的更改不會破壞你的合作伙伴開發(fā)者的應用。
了解主要和次要更新
小版本升級（Minor）：當變更不會破壞客戶端應用程序的運行時，可以使用小版本升級，例如添加可選字段或支持附加參數(shù)。這時候你可以為你的 API 增設小版本。
大版本升級（Major）：是那些肯定會破壞現(xiàn)有客戶端應用的版本，比如在請求參數(shù)中添加一個新的必需參數(shù)，或改變返回結(jié)果中的字段。
可以通過多種方式來對 API 進行版本控制。
最常見的方法是將版本包含在 URI 中。
https://api.domain.com/v1.0/authors
另外一種方法是使用基于日期的版本控制。URI 中包括將版本發(fā)布日期。應用程序開發(fā)人員可以很方便了解 API 更改的頻率。
https://api.domain.com/2020-06-15/authors
另一種方法是在請求標頭中包含 API 版本。
https://api.domain.com/authors
?x-api-version：v1
最推薦和接受的版本控制方式是，在URI 中使用版本名稱。
分頁
在數(shù)據(jù)量越來越大的世界里，不可能在一個屏幕上同時顯示所有的數(shù)據(jù)。所以，讓用戶在再次請求數(shù)據(jù)之前，先取到一定數(shù)量的結(jié)果，這一點很重要。這就是所謂的分頁，返回的數(shù)據(jù)集叫做頁面。
建議你在請求和返回結(jié)果中使用特定的術(shù)語來啟用 API 中的分頁功能。這些術(shù)語有
STRING page_token（在請求中發(fā)送） STRING next_page_token（由 API 返回） INT page_size（在請求中發(fā)送）
page_token 請求 API 需要返回哪個頁面。這通常是一個字符串。對于第一次API調(diào)用，page_token = "1"
page_size 定義了返回結(jié)果中應該返回多少條記錄。例如page_size = 100，在API調(diào)用中最多返回100條記錄。
next_page_token 定義了翻頁的下一個 token。如果在page_token = "1" 之后有額外的數(shù)據(jù)，返回的值是應當是 next_page_token="2"
如果沒有更多的數(shù)據(jù)可用，而且用戶已經(jīng)到達數(shù)據(jù)的終點，則返回一個空白值 next_page_token="" 。
這些就是設計 API 的最佳實踐。它讓你的 API 更健壯、簡潔并易于與其他應用程序集成。
請記住。
干貨分享
最近將個人學習筆記整理成冊，使用PDF分享。關(guān)注我，回復如下代碼，即可獲得百度盤地址，無套路領取！
?001：《Java并發(fā)與高并發(fā)解決方案》學習筆記；?002：《深入JVM內(nèi)核——原理、診斷與優(yōu)化》學習筆記；?003：《Java面試寶典》?004：《Docker開源書》?005：《Kubernetes開源書》?006：《DDD速成（領域驅(qū)動設計速成）》?007：全部?008：加技術(shù)群討論
加個關(guān)注不迷路
喜歡就點個"在看"唄^_^