7大技巧助你設(shè)計清晰易用API

每個編程人員渴望建立用戶友好的高效API。對于用戶，他們希望界面美觀直觀易用。然而，有一些策略可以提高API質(zhì)量，讓我們看看以下七個方案如何使您的API設(shè)計更加直觀便捷。

1. 保持一致

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

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

2. 簡化命名

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

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

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

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

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

如果您使用版本控制，請在樣式指南中包含指南，以便開發(fā)人員以相同的方式更新和棄用 API。您可以包含版本控制規(guī)則，例如：

始終對每個 API 應(yīng)用版本編號，并解釋編號方案。

切勿在 API URL 中包含版本號。

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

4. 嚴(yán)格指定

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

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

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

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

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

為什么？因為它允許第三方與您的 API 進(jìn)行集成。輕松的集成機(jī)會有助于采用和使用您的 API。

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

6. 利用分頁

分頁對于開發(fā)人員來說非常有價值，因為它允許您對返回資源集合的所有請求進(jìn)行分頁。在獲取這些記錄集合時，您還可以使用過濾和排序。

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

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

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

提供健康檢查接口。

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

在接口路徑中使用名詞。

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

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

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