使用API安全的基本工具和最佳實踐預(yù)防API攻擊
從開發(fā)人員的角度來看，良好的文檔可以節(jié)省時間。開發(fā)人員無需花費數(shù)小時來解讀和試驗 API 的功能，而是可以參考提供清晰說明、示例和故障排除提示的綜合文檔。這可以節(jié)省寶貴的開發(fā)時間并加快集成過程，使開發(fā)人員可以專注于構(gòu)建創(chuàng)新應(yīng)用程序。
此外，有效的 API 文檔可以改善 API 提供商和開發(fā)人員之間的協(xié)作。它充當(dāng)一種通用語言，促進(jìn)溝通并確保雙方意見一致。開發(fā)人員可以輕松了解 API 的預(yù)期行為、可用端點和所需參數(shù)，從而使他們能夠?qū)?API 無縫集成到他們的應(yīng)用程序中。
您的API 文檔受眾是細(xì)分的。因此，確定從您的文檔中受益的不同人群非常重要。這將讓您深入了解如何滿足他們的需求。
開發(fā)人員是直接使用您 API 的人。為了有效地使用您的 API，他們需要了解它如何應(yīng)用于他們的用例。此外，如果他們需要對 API 運行 QA 測試，他們需要盡可能多的有關(guān) API 的信息。他們可能需要學(xué)習(xí)如何訪問和集成您公開的數(shù)十個甚至數(shù)百個資源。
研究表明，多年來，開發(fā)人員對 API 文檔的信心越來越強(qiáng)。隨著數(shù)字的不斷增長，提供與 API 配套的相關(guān)技術(shù)文檔才是明智之舉。
這群人可能永遠(yuǎn)不會真正使用您的 API。他們負(fù)責(zé)確定團(tuán)隊所需的資源。其中一些人是技術(shù)人員，如 CTO，而其他人可能是 COO。確保您的 API 文檔在編寫時考慮到了這樣的受眾。
最后，記者、技術(shù)愛好者和其他非專業(yè)人士可能會看到您的 API 文檔。您如何定位他們？針對技術(shù)含量最低的受眾進(jìn)行撰寫。
在深入研究技術(shù)細(xì)節(jié)之前，必須先定義 API 文檔的目的和范圍。問問自己，文檔的目標(biāo)是什么？你希望開發(fā)人員通過閱讀文檔實現(xiàn)什么目標(biāo)？確定主要目標(biāo)并概述你需要涵蓋的主題。
考慮目標(biāo)受眾及其需求。他們是需要深入技術(shù)信息的開發(fā)人員，還是尋求高層次概述的業(yè)務(wù)用戶？相應(yīng)地調(diào)整詳細(xì)程度和使用的語言。
API 端點是 API 的支柱，定義可用的功能和操作。記錄每個端點，清晰描述其用途、支持的 HTTP 方法（例如 GET、POST、PUT、DELETE）以及預(yù)期的響應(yīng)格式。
包含 API 請求和響應(yīng)的示例，以說明預(yù)期行為。使用清晰簡潔的語言，盡可能避免使用技術(shù)術(shù)語。考慮使用數(shù)據(jù)結(jié)構(gòu)或圖表來可視化復(fù)雜的負(fù)載或資源之間的關(guān)系。
參數(shù)在 API 交互中起著至關(guān)重要的作用，允許開發(fā)人員自定義其請求并檢索特定數(shù)據(jù)。記錄每個參數(shù)，包括其名稱、數(shù)據(jù)類型、必需/可選狀態(tài)以及任何約束或驗證規(guī)則。
提供清晰的 API 請求構(gòu)造示例，展示參數(shù)的用法。考慮重點介紹可能需要不同參數(shù)的常見用例和場景。
對于接受請求負(fù)載的 API，請記錄負(fù)載的結(jié)構(gòu)和格式。指定必填字段、預(yù)期數(shù)據(jù)類型以及任何約束或驗證規(guī)則。包括有效負(fù)載的示例，以指導(dǎo)開發(fā)人員準(zhǔn)確構(gòu)建請求。
在 API 交互中，安全性至關(guān)重要。記錄 API 支持的身份驗證和授權(quán)方法，概述開發(fā)人員驗證其請求和訪問受保護(hù)資源所需采取的步驟。
解釋不同的身份驗證機(jī)制，例如 API 密鑰、OAuth 或 JWT，并提供有關(guān)如何獲取和使用必要憑據(jù)的明確說明。包括帶有身份驗證標(biāo)頭或令牌的 API 請求示例，以便更好地理解。
確保開發(fā)人員了解與每種身份驗證方法相關(guān)的授權(quán)范圍和權(quán)限。記錄所有確定授予不同用戶的訪問級別的訪問控制規(guī)則或角色。
開發(fā)人員通常通過實際示例和用例來獲得最佳學(xué)習(xí)效果。提供各種示例來演示如何在各種場景中使用 API。包含帶有代碼片段的分步說明，以指導(dǎo)開發(fā)人員完成常見任務(wù)或工作流程。
考慮提供多種編程語言的示例，以滿足具有不同背景的開發(fā)人員的需求。突出顯示任何可簡化 API 集成的特定語言庫、SDK 或框架。
對于復(fù)雜或高級用例，請考慮提供完整的代碼示例或參考實現(xiàn)。這些示例可作為開發(fā)人員的起點，展示最佳實踐和利用 API 的有效方法。
組織良好的文檔對于輕松導(dǎo)航和信息檢索至關(guān)重要。將信息分為邏輯部分并提供清晰的目錄。使用標(biāo)題、副標(biāo)題和項目符號來提高可讀性和可掃描性。
創(chuàng)建 API 文檔時最重要的步驟是清楚了解用戶的需求以及他們對文檔的期望。首先研究 API 的目標(biāo)受眾，并考慮他們的技術(shù)知識水平。這可以幫助您設(shè)計文檔，以最有效的方式滿足他們的需求。
當(dāng)為混合受眾寫作時，最明智的方法是針對讀者中最不了解技術(shù)的人。嘗試回答基本問題，在必要時給出解釋，并減少使用術(shù)語。以下是針對非技術(shù)受眾的一系列方法
講故事：利用案例并圍繞案例講故事。這可以吸引各種類型的受眾，并展示您的產(chǎn)品的實際效果。
詳盡：將所有重要信息都寫出來很重要，但你應(yīng)該盡量用最少的文字來表達(dá)。寫一個大綱，讓你把概念分解成簡潔的部分。
具有指導(dǎo)意義：讓用戶知道從哪里開始，從哪里結(jié)束。以清晰的步驟詳細(xì)說明復(fù)雜的信息。在必要時提供示例。
您的讀者希望獲得盡可能多的幫助。不要吝嗇提供信息。指出他們可能需要的任何相關(guān)指南和支持資源。不要讓他們猜測。支持文檔的一些示例如下：
入門指南：這提供了使用 API 的全面方法。目標(biāo)是確保您的消費者能夠成功使用您的產(chǎn)品。
交互式控制臺：控制臺可幫助您的受眾測試您的 API 并實時查看結(jié)果。這是一種簡單的方法，但能帶來巨大的回報。
庫：代碼庫使開發(fā)人員能夠輕松調(diào)用不同的資源。訪問不同語言的方法以使用您的 API 有助于開發(fā)人員更輕松地使用 API。
讓讀者輕松理解您的文檔；使用熟悉的布局和設(shè)計。如果您使用文檔生成器，那么布局已經(jīng)為您決定了。
以下是一些建議：使用良好的對比度：Web 內(nèi)容可訪問性指南 2.1 (WCAG) 建議圖形和用戶界面組件（如表單輸入邊框）的對比度至少為 3:1。WCAG AAA 級要求普通文本的對比度至少為 7:1，大文本的對比度至少為 4.5:1。
使用動態(tài)布局：如今，布局必須易于添加書簽。使用 PDF 和單頁文檔并不合適。確保您的文檔是動態(tài)且可擴(kuò)展的。
導(dǎo)航欄：導(dǎo)航欄應(yīng)緊貼屏幕。讓用戶輕松切換頁面。
您的用戶不應(yīng)該對 API 響應(yīng)感到驚訝。他們應(yīng)該確切地知道 API 調(diào)用會帶來什么結(jié)果。
記錄 API 可能提供的所有與參數(shù)和響應(yīng)相關(guān)的調(diào)用。響應(yīng)可作為用戶的上下文指南，顯示他們是否走在正確的道路上。
響應(yīng)還會提供錯誤消息指導(dǎo)?？偟膩碚f，這有助于您的用戶取得成功。在描述完整的示例響應(yīng)正文時，請務(wù)必涵蓋多種格式。
最后，示例很重要。在您的 API 應(yīng)返回的每個對象中提供示例，以及消費者可為成功 API 調(diào)用添加的參數(shù)示例。API 可觀察性工具可以提供幫助。
在使用任何 API 時，錯誤都是不可避免的一部分，因此在文檔中清楚地解釋錯誤非常重要。這樣，用戶就會明白為什么會出現(xiàn)錯誤，并知道要采取哪些步驟來解決問題。提供常見錯誤消息的示例也有助于用戶在故障排除時參考。務(wù)必對每條錯誤消息提供良好的描述，并解釋錯誤發(fā)生的原因。
相信我，真正讓開發(fā)人員惱火的一件事就是封閉的 API 文檔。不要被愚弄，封閉的文檔不會增加轉(zhuǎn)化率。開發(fā)人員和決策者在決定使用您的 API 之前想知道會發(fā)生什么。
根據(jù)需要使用盡可能多的代碼示例。開發(fā)人員對此非常感激。不要只說不做示例。
最后，針對搜索引擎進(jìn)行優(yōu)化。如果無法通過簡單的 Google 搜索找到您的文檔，那么它們就毫無用處。確保頁面已編入索引、標(biāo)題正確且描述清晰。
沒有人喜歡過時的文檔，請定期更新您的 API 文檔。以下是一些建議：
擁有標(biāo)準(zhǔn)的更新流程/框架：將您的文檔納入 API 更新流程。這可確保您在推出新功能時，您的文檔也已準(zhǔn)備好發(fā)布。
經(jīng)常檢查：經(jīng)常檢查文檔可以發(fā)現(xiàn)過時的地方。安排檢查時間可以保持流程的精簡。
使用分析：良好的 API 分析將顯示最常使用的端點。這將為您的 API 文檔審查過程提供信息，幫助您將更新重點放在最常用的部分上。
雖然 API 文檔至關(guān)重要，但它也存在一些挑戰(zhàn)。讓我們來探討一下 API 提供商在創(chuàng)建文檔時面臨的一些常見障礙以及如何克服這些障礙：
原文鏈接：How to Write API Documentation: 14 Essential Guidelines
