一個(gè)高質(zhì)量的API目錄具備以下幾個(gè)關(guān)鍵特征：

• 可搜索性：它們提供搜索或過(guò)濾功能，使開(kāi)發(fā)人員能夠輕松縮小選擇范圍。這不僅幫助用戶(hù)在多個(gè)選項(xiàng)中做出決策，而且避免了單一工具的局限。
• 信息豐富：每個(gè)API的目錄條目都提供清晰、一致的快照，方便開(kāi)發(fā)人員比較和選擇。目標(biāo)是為用戶(hù)提供足夠的信息，幫助他們構(gòu)建API程序的思維導(dǎo)圖。
• 引導(dǎo)性強(qiáng)：它們提供清晰的前進(jìn)路徑，包括高質(zhì)量文檔和“入門(mén)”資源的鏈接，以便開(kāi)發(fā)人員能夠快速實(shí)現(xiàn)他們所需的工具。

同時(shí)，我們也應(yīng)該了解API目錄不是什么：

• 非替代品：API目錄不能替代詳盡的文檔。它們只是第一步，用戶(hù)仍需深入了解如何使用API。
• 非推銷(xiāo)工具：API目錄是為尋找實(shí)用解決方案的開(kāi)發(fā)人員提供的資源，它們必須真實(shí)、直接，避免廢話。
• 非索引或數(shù)據(jù)庫(kù)：雖然您可能在其他地方擁有所有API的列表，但目錄是以用戶(hù)需求為先的方式組織和呈現(xiàn)的。它們是為消費(fèi)者設(shè)計(jì)的，以便更快地找到所需的解決方案。

公共與私人API目錄：定制化的開(kāi)發(fā)工具

無(wú)論您是在開(kāi)發(fā)面向公眾的API，還是構(gòu)建服務(wù)于私有和合作伙伴的API服務(wù)架構(gòu)，API目錄都扮演著一個(gè)強(qiáng)大的工具角色。它們?cè)谌魏吻闆r下都能促進(jìn)API的發(fā)現(xiàn)，并引導(dǎo)開(kāi)發(fā)人員找到最合適的解決方案。

考慮API目錄的受眾和目的是至關(guān)重要的，這將幫助您確定哪些功能最為關(guān)鍵。對(duì)于公共API，目錄應(yīng)該易于被廣泛的開(kāi)發(fā)者發(fā)現(xiàn)和訪問(wèn)。而對(duì)于私有API，目錄可能需要更注重安全性和對(duì)特定合作伙伴的可訪問(wèn)性。

明確您的API目錄是為了服務(wù)廣大開(kāi)發(fā)者，還是為了滿(mǎn)足特定組織或合作伙伴的需求，這將影響您在設(shè)計(jì)目錄時(shí)應(yīng)考慮的特性和功能。例如，公共API目錄可能需要更強(qiáng)大的搜索和過(guò)濾功能，而私有API目錄可能更注重權(quán)限管理和定制化訪問(wèn)。

通過(guò)精心設(shè)計(jì)您的API目錄，您可以確保它不僅能吸引開(kāi)發(fā)者，而且能夠提供他們所需的信息，從而促進(jìn)您的API被有效利用。

通過(guò)API目錄推動(dòng)公共API的貨幣化

開(kāi)發(fā)人員常常長(zhǎng)期使用某個(gè)工具而不自知其屬于更廣泛解決方案的一部分。這種現(xiàn)象并非僅限于API。實(shí)際上，在2007年之前，對(duì)Microsoft Office產(chǎn)品的90%以上功能請(qǐng)求已存在于產(chǎn)品中。用戶(hù)一旦找到解決問(wèn)題的方法，很少會(huì)進(jìn)一步探索其他功能。API目錄能夠展示您的全系列API產(chǎn)品，使用戶(hù)能夠快速發(fā)現(xiàn)更強(qiáng)大的解決方案，實(shí)現(xiàn)更深入的集成，并挖掘更大的收入潛力。

尼爾森諾曼集團(tuán)（Nielsen Norman Group, NNG）提出了幾種策略，鼓勵(lì)用戶(hù)進(jìn)一步探索，以下是API目錄可以幫助實(shí)現(xiàn)的一些策略：

• 可見(jiàn)功能：NNG建議，“不要讓人們搜索關(guān)鍵功能。”API目錄的目的正是讓選項(xiàng)顯而易見(jiàn)，無(wú)需搜索。一個(gè)友好的瀏覽界面可以鼓勵(lì)探索，并引導(dǎo)用戶(hù)發(fā)現(xiàn)他們未曾考慮過(guò)的產(chǎn)品類(lèi)別。
• 可見(jiàn)的標(biāo)志：圖標(biāo)或縮略圖網(wǎng)格，配合可掃描的文本，比純文本列表更容易被潛在用戶(hù)理解。視覺(jué)元素可以清晰展示API產(chǎn)品之間的關(guān)系，并突出重要特性和功能。強(qiáng)調(diào)可操作按鈕而非文本的用戶(hù)體驗(yàn)可以鼓勵(lì)用戶(hù)采取行動(dòng)。
• 即時(shí)學(xué)習(xí)：API目錄將實(shí)現(xiàn)細(xì)節(jié)放在需要時(shí)展示。向開(kāi)發(fā)人員過(guò)早提供大量信息可能會(huì)造成反感。最有用的功能應(yīng)在目錄頂層可見(jiàn)，而系統(tǒng)要求和兼容性的關(guān)鍵細(xì)節(jié)應(yīng)隨時(shí)可用，但具體的文檔細(xì)節(jié)可以留待開(kāi)發(fā)人員完成瀏覽后再提供。
• 低承諾預(yù)覽：讓用戶(hù)在安裝或注冊(cè)之前了解將會(huì)發(fā)生什么。API目錄是展示快速GIF或圖表的理想場(chǎng)所，使用戶(hù)能夠清楚了解功能。

通過(guò)這些策略，API目錄不僅能幫助用戶(hù)發(fā)現(xiàn)新的解決方案，還能提升用戶(hù)體驗(yàn)，從而推動(dòng)公共API的貨幣化。

為內(nèi)部開(kāi)發(fā)人員提供高效的API解決方案

盡管您可能主要處理內(nèi)部私有API，認(rèn)為API目錄與您的需求不太相關(guān)，但實(shí)際上，API目錄對(duì)私有API程序的作用與公共API程序有很多相似之處。即使您不打算將API作為收入中心，提高API的可發(fā)現(xiàn)性和突出最佳實(shí)踐也能為您帶來(lái)顯著的好處。

在大型微服務(wù)架構(gòu)中，API目錄尤其有用。它們可以通過(guò)以下方式提高效率：

• 通過(guò)簡(jiǎn)化查找已有解決方案的過(guò)程，防止開(kāi)發(fā)重復(fù)的API。
• 通過(guò)推廣使用首選工具和版本，加強(qiáng)API治理。
• 通過(guò)宣傳能節(jié)省時(shí)間的工具，合理分配團(tuán)隊(duì)資源。

對(duì)于內(nèi)部團(tuán)隊(duì)而言，API目錄充當(dāng)著知識(shí)庫(kù)和代碼存儲(chǔ)庫(kù)之間的橋梁。它不僅是最佳實(shí)踐的信息來(lái)源，也是幫助新API更有效集成的工具。與公共API目錄相比，私有API目錄可以更加定制化，以滿(mǎn)足您對(duì)內(nèi)部團(tuán)隊(duì)用例和開(kāi)發(fā)生命周期的了解。您可以調(diào)整目錄的內(nèi)容和格式，引導(dǎo)開(kāi)發(fā)人員遵循最佳實(shí)踐，實(shí)現(xiàn)服務(wù)架構(gòu)的一致性。

隨著新的產(chǎn)品工程團(tuán)隊(duì)的快速發(fā)展，API目錄還能減輕DevOps團(tuán)隊(duì)的負(fù)擔(dān)。目錄使開(kāi)發(fā)團(tuán)隊(duì)能夠快速識(shí)別組織內(nèi)其他地方正在使用的API，從而利用其他團(tuán)隊(duì)的專(zhuān)業(yè)知識(shí)和工作成果。對(duì)于DevOps團(tuán)隊(duì)而言，目錄是一種簡(jiǎn)單有效的方法來(lái)分享最佳實(shí)踐和解答問(wèn)題，減少對(duì)工程團(tuán)隊(duì)支持的變量。

探索API目錄，激發(fā)創(chuàng)新靈感

如果您正考慮構(gòu)建自己的API目錄，不妨先看看一些成功的示例。這些示例不僅能給您帶來(lái)靈感，還能展示API目錄的最佳實(shí)踐：

• Meta開(kāi)發(fā)者文檔：Meta（Facebook的前身）提供了豐富的API資源，其目錄設(shè)計(jì)強(qiáng)調(diào)了品牌和清晰的分類(lèi)，便于快速瀏覽。
• Twilio API參考：Twilio的目錄在首頁(yè)提供了精選的API信息，并提供了基于用例和開(kāi)發(fā)平臺(tái)的篩選功能，幫助用戶(hù)迅速縮小選擇范圍。
• Slack API：Slack以簡(jiǎn)潔的類(lèi)別組織API，并為最常用的API提供了詳細(xì)信息。它的設(shè)計(jì)鼓勵(lì)用戶(hù)探索，同時(shí)保持了側(cè)邊欄的簡(jiǎn)潔性。
• 亞馬遜銷(xiāo)售合作伙伴API：雖然找到這個(gè)目錄可能有點(diǎn)困難，但一旦到達(dá)，開(kāi)發(fā)者會(huì)發(fā)現(xiàn)一個(gè)清晰、易于導(dǎo)航的目錄，它提供了與亞馬遜電商集成相關(guān)的所有API。

接下來(lái)，我們將進(jìn)一步探討API目錄能為您的API團(tuán)隊(duì)帶來(lái)的好處和局限。同時(shí)，當(dāng)您使用API、開(kāi)發(fā)者工具、應(yīng)用程序和網(wǎng)站時(shí)，請(qǐng)留意那些促進(jìn)發(fā)現(xiàn)的用戶(hù)體驗(yàn)。什么樣的體驗(yàn)?zāi)茏屇钊氲亓私獠⑻剿鳟a(chǎn)品的新用例和功能？

您的API和DevOps團(tuán)隊(duì)構(gòu)建的產(chǎn)品值得被那些能夠最有效地使用它們的開(kāi)發(fā)者發(fā)現(xiàn)。將您對(duì)激發(fā)發(fā)現(xiàn)的觀察應(yīng)用到您的API目錄中，可以成為改善開(kāi)發(fā)人員體驗(yàn)的有力工具。

文件鏈接來(lái)自：https://blog.stoplight.io/api-products-need-api-catalogs