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