每個(gè)開(kāi)發(fā)人員都希望創(chuàng)建一個(gè)方便易用的 API。每個(gè)用戶都希望有一個(gè)不混亂或難以導(dǎo)航的界面。幸運(yùn)的是，開(kāi)發(fā)人員可以使用一些技巧來(lái)改進(jìn)他們的 API。事不宜遲，以下是 7 個(gè)技巧，它們將使您的 API 設(shè)計(jì)清晰便捷。

1. 保持一致

首先，開(kāi)發(fā) API 時(shí)需要保持一致。您針對(duì) API 所做的一切都需要標(biāo)準(zhǔn)化和組織化，以確保盡可能保持一致。如果您的行動(dòng)不一致，最終可能會(huì)得到設(shè)計(jì)不良的 API，無(wú)法按照您想要的方式運(yùn)行。

例如，在命名項(xiàng)目時(shí)，您需要使用一種特定的邏輯來(lái)命名，而不是每次都以新的方式命名。從技術(shù)層面上講，您還應(yīng)該關(guān)注與 API 相關(guān)的文檔，并確保其準(zhǔn)確且一致。在與 API 相關(guān)的所有工作中，都要保持這種觀點(diǎn)。

2. 簡(jiǎn)化命名

說(shuō)到命名，簡(jiǎn)化項(xiàng)目的名稱絕對(duì)是一個(gè)好主意。您需要以一種簡(jiǎn)單且不言自明的方式命名它們，這將幫助您避免混淆。避免混淆項(xiàng)目以及讓您的團(tuán)隊(duì)在處理 API 時(shí)保持一致都很重要。

如果沒(méi)有一些指導(dǎo)，每個(gè)開(kāi)發(fā)人員都會(huì)獨(dú)立決定使用什么命名約定，事情可能會(huì)變得一團(tuán)糟。您最終可能會(huì)得到包含單個(gè)名詞、復(fù)數(shù)名詞和行話的接口。您還可能會(huì)得到包含不一致的大寫(xiě)字母和小寫(xiě)字母以及下劃線和破折號(hào)的接口和屬性。一旦開(kāi)發(fā)人員在 API 中命名了事物，這些名稱通常就不能輕易更改，因?yàn)檫@可能會(huì)對(duì) API 使用者造成重大影響。在您的風(fēng)格指南中包含一個(gè)概述命名約定的部分是非常值得的。

想象一下，當(dāng)您的團(tuán)隊(duì)成員中有些人以一種方式命名物品，而其他人則以完全不同的方式命名物品時(shí)。溝通不暢和混亂是必然會(huì)發(fā)生的。這就是為什么您需要事先就命名系統(tǒng)達(dá)成一致，并使其盡可能簡(jiǎn)單明了。無(wú)需讓事情復(fù)雜化。

3. 標(biāo)準(zhǔn)化響應(yīng)和版本控制

除了就命名項(xiàng)目系統(tǒng)達(dá)成一致外，您還應(yīng)該標(biāo)準(zhǔn)化錯(cuò)誤響應(yīng)，而不是嘗試發(fā)明一些不需要發(fā)明的東西。大多數(shù)情況下，您需要做的就是查看類似 API 的現(xiàn)有示例，看看它們?cè)诓煌闆r下使用哪種錯(cuò)誤消息。然后，您可以將相同的錯(cuò)誤消息用于您自己的 API。

如果您使用版本控制，請(qǐng)?jiān)跇邮街改现邪改希员汩_(kāi)發(fā)人員以相同的方式更新和棄用 API。您可以包含版本控制規(guī)則，例如：

始終對(duì)每個(gè) API 應(yīng)用版本編號(hào)，并解釋編號(hào)方案。

切勿在 API URL 中包含版本號(hào)。

始終在 API 標(biāo)頭中包含版本號(hào)。

4. 嚴(yán)格指定

您可能已經(jīng)注意到到目前為止列出的所有技巧的總體主題。簡(jiǎn)而言之，如果您想充分利用設(shè)計(jì)并確保您的用戶像您一樣喜歡它，您需要在使用 API 時(shí)井然有序。這正是您在指定 API 的不同方面時(shí)需要嚴(yán)格的原因。

例如，在設(shè)計(jì)接口、命名字段等時(shí)，您也應(yīng)該具體。這將幫助您避免混淆，但在某些情況下，它實(shí)際上對(duì)于以正確的方式創(chuàng)建特定元素或項(xiàng)目至關(guān)重要。認(rèn)真對(duì)待工作并嚴(yán)格指定所有內(nèi)容。

在 API 樣式指南中定義開(kāi)發(fā)人員應(yīng)遵循的單位、格式和標(biāo)準(zhǔn)。定義什么可能取決于您的行業(yè)，但“某些類型的數(shù)據(jù)（如日期時(shí)間）相對(duì)通用。”

5. 接受 API 密鑰認(rèn)證

除了考慮用戶之外，您還應(yīng)該考慮將來(lái)開(kāi)發(fā) API 并將其與其他應(yīng)用程序集成的潛力。雖然您永遠(yuǎn)無(wú)法準(zhǔn)確預(yù)測(cè)事情，但您可以肯定，接受API 密鑰身份驗(yàn)證在未來(lái)肯定會(huì)有用。

為什么？因?yàn)樗试S第三方與您的 API 進(jìn)行集成。輕松的集成機(jī)會(huì)有助于采用和使用您的 API。

許多早期的 API 都使用了 API 密鑰。雖然它們可能不是現(xiàn)在最新的安全標(biāo)準(zhǔn)，但它們通常比在 API 代碼中傳遞其他憑據(jù)有所改進(jìn)。API 密鑰存在缺點(diǎn)，但它們也是確保訪問(wèn)安全的簡(jiǎn)單方法。

6. 利用分頁(yè)

分頁(yè)對(duì)于開(kāi)發(fā)人員來(lái)說(shuō)非常有價(jià)值，因?yàn)樗试S您對(duì)返回資源集合的所有請(qǐng)求進(jìn)行分頁(yè)。在獲取這些記錄集合時(shí)，您還可以使用過(guò)濾和排序。

您的收藏會(huì)隨著時(shí)間的推移而增長(zhǎng)，因此您需要盡早開(kāi)始限制和控制返回的元素?cái)?shù)量。您還需要讓用戶對(duì)此有一定的控制權(quán)，但仍然需要預(yù)定義將顯示的對(duì)象數(shù)量。

7. 嘗試不同的技術(shù)手段

最后但并非最不重要的一點(diǎn)是，在開(kāi)發(fā) API 時(shí)，不要害怕嘗試不同的技術(shù)技巧和竅門。您可能會(huì)遇到比實(shí)際實(shí)施的更多可以嘗試的事情，因此最好有多種選擇。以下是您在設(shè)計(jì) API 時(shí)可以嘗試的一些技術(shù)技巧：

提供健康檢查接口。

使用合理的HTTP狀態(tài)代碼和方法。

在接口路徑中使用名詞。

提供擴(kuò)展的響應(yīng)選項(xiàng)。

使用 SSL 確保安全并配置 CORS。

總而言之，創(chuàng)建用戶喜歡的良好 API 設(shè)計(jì)絕對(duì)是開(kāi)發(fā)網(wǎng)站或應(yīng)用程序的最重要方面之一。