RESTful 接口的使用注意點(diǎn)

• 前言
• 為什么要使用 API？
• 數(shù)據(jù)建模與結(jié)構(gòu)化
• 編寫(xiě)面向資源的 API
• RESTful 接口
• API 版本控制
• 了解主要和次要更新
• 分頁(yè)

前言

良好設(shè)計(jì)的API = 快樂(lè)的程序員 ??。

應(yīng)用程序接口（API）是一種接口，它讓?xiě)?yīng)用程序可以輕松地使用另一個(gè)應(yīng)用程序的數(shù)據(jù)和資源，API 對(duì)于一個(gè)產(chǎn)品或公司的成功至關(guān)重要。

如果沒(méi)有 API，你大部分喜歡的軟件今天就不會(huì)存在。例如，Google Maps API 可以讓你在 app 或 Web 應(yīng)用中使用 Google Maps。如果沒(méi)有它，你將不得不設(shè)計(jì)和開(kāi)發(fā)自己的地圖數(shù)據(jù)庫(kù)。這樣的話，在地圖上顯示一個(gè)位置需要花費(fèi)多少時(shí)間？

為什么要使用 API？

1. API 可以讓外部應(yīng)用訪問(wèn)您的資源
2. API 擴(kuò)展了應(yīng)用程序的功能
3. API 允許開(kāi)發(fā)者重用應(yīng)用邏輯
4. API 是獨(dú)立于平臺(tái)的，它們傳遞數(shù)據(jù)不受請(qǐng)求平臺(tái)的影響

在大多數(shù)實(shí)際場(chǎng)景中，數(shù)據(jù)模型 已經(jīng)存在，但由于我們將討論 API 設(shè)計(jì)最佳實(shí)踐，我將從頭開(kāi)始說(shuō)起。

數(shù)據(jù)建模與結(jié)構(gòu)化

以 API 為中心對(duì)您的數(shù)據(jù)進(jìn)行建模，是設(shè)計(jì)易于創(chuàng)建、維護(hù)和更新 API 的第一步

在設(shè)計(jì) API 時(shí)，盡量考慮使用通用的術(shù)語(yǔ)，而不是使用內(nèi)部的復(fù)雜業(yè)務(wù)術(shù)語(yǔ)，因?yàn)檫@些術(shù)語(yǔ)在公司外可能不為人所知。你的 API 可能會(huì)對(duì)外開(kāi)放，以允許外部開(kāi)發(fā)人員使用你的 API 開(kāi)發(fā)他們自己的應(yīng)用。通過(guò)使用通用術(shù)語(yǔ)，你可以確保使用 API 的開(kāi)發(fā)人員易于了解你的 API，并能快速上手。

假設(shè)到你正在建立一個(gè)門(mén)戶網(wǎng)站，讓用戶點(diǎn)評(píng)不同作者的書(shū)籍。你的公司可能會(huì)使用特定的術(shù)語(yǔ)，如創(chuàng)作者、創(chuàng)作、系列等來(lái)指代圖書(shū)作者、書(shū)籍和系列。但為了簡(jiǎn)單起見(jiàn)，并方便外部應(yīng)用開(kāi)發(fā)者使用你的 API，使用通用的概念而不是公司特定的術(shù)語(yǔ)來(lái)創(chuàng)建 API 路徑。

https://api.domain.com/authors
?https://api.domain.com/authors/{id}/books

這有助于新的開(kāi)發(fā)人員快速了解你的 API 是什么，以及如何遍歷你的數(shù)據(jù)模型。

編寫(xiě)面向資源的 API

應(yīng)用程序需要訪問(wèn)你的資源。維護(hù)一個(gè)資源層次結(jié)構(gòu)可以幫助你更好地構(gòu)建 API。資源層次結(jié)構(gòu)是指路徑中的每個(gè)節(jié)點(diǎn)，它由一個(gè)集合或一個(gè)資源組成。

資源可以是一個(gè)單一的數(shù)據(jù)，例如，上面例子中的作者簡(jiǎn)介。

集合是指一個(gè)資源的集合，在我們的例子中，它可以是一個(gè)作者所寫(xiě)的書(shū)的列表。

合適的資源層次結(jié)構(gòu)可以是：

Base?Path?->?作者?(集合)?->?profile?(資源)
Base?Path?->?作者?(集合)?->?書(shū)?(集合)?->?書(shū)?(資源)

層次結(jié)構(gòu)需要保持一致，以確保開(kāi)發(fā)人員在將其應(yīng)用程序接入 API 時(shí)遇到的問(wèn)題最少。

為了保持簡(jiǎn)單性和一致性，這里有一些指導(dǎo)原則可以幫助你：

1. 命名集合和資源時(shí)使用美式英語(yǔ)（例如：color 而不是 colour）
2. 避免拼寫(xiě)錯(cuò)誤
3. 使用更簡(jiǎn)單、更常用的詞來(lái)保持清晰，例如 delete 而不是 remove
4. 如果你使用的資源與其他 API 使用的資源相同，請(qǐng)使用相同的術(shù)語(yǔ)以保持一致。
5. 對(duì)集合使用復(fù)數(shù)形式（例如：authors、books 等）。

RESTful 接口

HTTP 形式的 API 最廣泛接受的標(biāo)準(zhǔn)是 REST(Representational State Transfer)。它基本上意味著每個(gè) URL 代表一個(gè)對(duì)象。

API 目的可以是以下之一：

1. 創(chuàng)建數(shù)據(jù) Create
2. 讀取數(shù)據(jù) Read
3. 更新數(shù)據(jù) Update
4. 刪除數(shù)據(jù) Delete

CRUD！猜對(duì)了!

API 通過(guò)使用一組 HTTP 命令來(lái)處理，這些命令定義了請(qǐng)求的性質(zhì)和它應(yīng)該做什么。

GET 從 API 中檢索數(shù)據(jù)。它要求從 API 中獲取數(shù)據(jù)的表示。GET請(qǐng)求可以包含查詢參數(shù)，以過(guò)濾從API接收的結(jié)果。

POST 向 API 提交一條記錄，該記錄將在數(shù)據(jù)庫(kù)中創(chuàng)建一個(gè)資源。

PUT 一般用于更新服務(wù)器上的現(xiàn)有資源。

DELETE 從服務(wù)器上刪除一個(gè)資源。

API 版本控制

應(yīng)用程序和 API 的生命周期越長(zhǎng)，應(yīng)用和 API 對(duì)用戶的承諾就越大。在某個(gè)時(shí)間點(diǎn)上，你的 API 將需要修改，因?yàn)槟銦o(wú)法預(yù)見(jiàn)隨著需求和業(yè)務(wù)政策而發(fā)生的變化。

因此需要對(duì) API 進(jìn)行更改。但是 API 可能已經(jīng)有一個(gè)或多個(gè)開(kāi)發(fā)者在使用了，所以，重要的是，你所做的更改不會(huì)破壞你的合作伙伴開(kāi)發(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)用的版本，比如在請(qǐng)求參數(shù)中添加一個(gè)新的必需參數(shù)，或改變返回結(jié)果中的字段。

可以通過(guò)多種方式來(lái)對(duì) API 進(jìn)行版本控制。

最常見(jiàn)的方法是將版本包含在 URI 中。

https://api.domain.com/v1.0/authors

另外一種方法是使用基于日期的版本控制。URI 中包括將版本發(fā)布日期。應(yīng)用程序開(kāi)發(fā)人員可以很方便了解 API 更改的頻率。

https://api.domain.com/2020-06-15/authors

另一種方法是在請(qǐng)求標(biāo)頭中包含 API 版本。

https://api.domain.com/authors
?x-api-version：v1

最推薦和接受的版本控制方式是，在URI 中使用版本名稱。

分頁(yè)

在數(shù)據(jù)量越來(lái)越大的世界里，不可能在一個(gè)屏幕上同時(shí)顯示所有的數(shù)據(jù)。所以，讓用戶在再次請(qǐng)求數(shù)據(jù)之前，先取到一定數(shù)量的結(jié)果，這一點(diǎn)很重要。這就是所謂的分頁(yè)，返回的數(shù)據(jù)集叫做頁(yè)面。

建議你在請(qǐng)求和返回結(jié)果中使用特定的術(shù)語(yǔ)來(lái)啟用 API 中的分頁(yè)功能。這些術(shù)語(yǔ)有

1. STRING page_token（在請(qǐng)求中發(fā)送）
2. STRING next_page_token（由 API 返回）
3. INT page_size（在請(qǐng)求中發(fā)送）

page_token 請(qǐng)求 API 需要返回哪個(gè)頁(yè)面。這通常是一個(gè)字符串。對(duì)于第一次API調(diào)用，page_token = "1"

page_size 定義了返回結(jié)果中應(yīng)該返回多少條記錄。例如page_size = 100，在API調(diào)用中最多返回100條記錄。

next_page_token 定義了翻頁(yè)的下一個(gè) token。如果在page_token = "1" 之后有額外的數(shù)據(jù)，返回的值是應(yīng)當(dāng)是 next_page_token="2"

如果沒(méi)有更多的數(shù)據(jù)可用，而且用戶已經(jīng)到達(dá)數(shù)據(jù)的終點(diǎn)，則返回一個(gè)空白值 next_page_token="" 。

這些就是設(shè)計(jì) API 的最佳實(shí)踐。它讓你的 API 更健壯、簡(jiǎn)潔并易于與其他應(yīng)用程序集成。

請(qǐng)記住。

良好設(shè)計(jì)的API = 快樂(lè)的程序員 ??。