開發者資源#

打造出色的 API 還不夠，如果沒有人知道如何使用它，一切都是白費。在設計 API 的同時，你必須透過提供學習材料來引導並賦能開發者，幫助他們成功。

開發者資源（Developer Resources）是一組你應該提供給開發者的資產，讓他們能夠更有效地使用你的 API。開發者資源有很多類型，各自影響開發生命週期的不同面向。本章涵蓋大多數公司會提供的主要資源，並分享一些實用的技巧。

API 文件#

最基本的資源就是文件（Documentation）。

文件是開發者學習你的 API 的入口。無論你提供的是簡單的 README 檔案，還是為開發者打造完整的網站，清楚地記載如何最有效地使用你的 API 至關重要。好的文件應涵蓋開發生命週期的所有階段，包含以下幾個面向。

Getting Started 入門指南#

Getting Started 指南是一種常見的教學文件，引導開發者從對 API 陌生到獲得初步成功。在許多情況下，這以完成一個「Hello World」練習的形式呈現——這指的是工程界的慣例：讓程式或 API 輸出「Hello World」作為成功的證明。

API 不必真的回傳「Hello, world」，但你可以讓使用者達到以下任一里程碑：

  • 成功發出一次 API 請求
  • 開啟一個 WebSocket 連線並收到第一個事件
  • 從 WebHook 收到一個範例 POST 請求

Getting Started 指南的目標是列出開發者需要採取的最簡單、最快速的步驟，也就是所謂的 TTHW（Time to Hello World）。

將 Getting Started 指南放在 API 網站最顯眼的位置，對於新開發者的導入（onboarding）至關重要。簡化並縮短 TTHW 能顯著提升開發者對 API 的採用率。

單一的 Getting Started 指南適用於簡單的使用情境，但如果你的 API 較複雜且涵蓋多種使用情境，應以額外的入門文件來擴展。例如：

  • 「建立你的第一個 Web App」
  • 「開始儲存你的資料」
  • 「用戶驗證入門」

以下是好的 Getting Started 指南的關鍵要素：

  • 不要假設讀者具備先備知識——盡可能解釋每個技術術語（可透過連結或彈出視窗引導讀者參閱更深入的文獻）。如果有前置條件，提供對應的 Getting Started 文件連結。
  • 不要偏離 happy path——假設一切順利進行，但為出錯的情況提供疑難排解（troubleshooting）文件的連結。不要讓開發者陷入困境。
  • 展示輸入與輸出的範例——如果開發者需要執行命令列，展示該命令列的範例；如果有預期結果，展示該結果的截圖。展示每個方法的各種排列組合及對應的輸出。
  • 盡量展示最簡單用法的範例程式碼——如果不會太長或太繁瑣，提供展示基本用法的範例。
  • 以行動呼籲（call to action）和其他參考資源連結作結——不要讓開發者卡住，給他們方向和資源來擴展知識。
專家建議：Stripe 的開發者體驗

正確的 API 設計能創造引人入勝且令人愉悅的開發者體驗，而經過深思熟慮的導入流程對於開發者即時理解 API 運作方式並快速在其上構建至關重要。例如，Stripe 動態且個人化的開發者文件提供了可快速加入現有應用程式的客製化程式碼範例，我們還提供主流程式語言的一流函式庫。API 端點、參數、資料模型和錯誤訊息在整個平台上都經過仔細定義且保持一致。開發者支援也是核心產品體驗的一部分，我們努力在數小時（甚至數分鐘）內做出回應。我們相信這些接觸點創造了優雅的 API 設計，確保開發者成功，以指數方式提升他們的生產力。

回顧十年前，創業並在線上接受付款是難以置信的困難。除了自建解決方案、建立商戶帳號、閱讀數百頁文件只為接受一筆簡單的付款之外別無選擇。在 Stripe，我們將支付視為根植於程式碼而非金融的問題。我們的 API 設計讓開發者能在幾分鐘內從世界任何地方、使用任何支付方式接受付款。

—— Romain Huet，Stripe 開發者關係負責人

API 參考文件#

這是文件中非常技術性的部分，可以使用 Swagger 等工具自動生成。參考文件是對所有 API 方法、其輸入與輸出參數，以及可能回傳的錯誤的詳細描述。

Figure 9.1: Twitch's API reference page

參考文件的關鍵原則：

  • 應全面且完整——不用擔心重複共通的章節，因為這類文件並非設計為按順序閱讀。例如，如果一個錯誤出現在兩個方法中，務必在兩個章節都重複錯誤描述和原因。
  • 每個 API 方法獨立一頁——因為使用者通常透過 Google 搜尋或內部搜尋存取這些頁面，這樣做能提升可發現性（discoverability）和可用性。
  • 加入 API 使用範例——甚至可以加入內建的 API 測試器，讓開發者開始試驗 API。
  • 在單一頁面內提供開發者所需的一切——並附上實用的額外資源連結。

教學文件（Tutorials）#

在文件的教學區塊中，你提供 API 不同面向的逐步操作指引。例如，你可以撰寫關於安全性或速率限制的文章。先從 API 的複雜部分開始，然後在有餘力時再處理較簡單的部分。

Figure 9.2: Shopify's API tutorials

與你的支援團隊合作，詢問哪些主題產生最多的支援工單。利用這些資訊來針對對你的受眾最困難的主題建立教學文件。定期這樣做能確保你總是在記錄高頻率的問題。

教學文件的注意事項：

  • 必須隨 API 更新而更新——否則它們會從指引變成誤導。
  • 可依元資訊（如程式語言）分類排序——讓開發者更容易找到所需的內容。
專家建議：Taylor Singletary 談教學文件

我覺得最有效的差異化方式之一是「How to X with Y」類型的教學：「如何用 Apache 和 mod_security 保護你的應用」或「如何用 QuickBasic 撰寫機器人」。

—— Taylor Singletary，Slack 首席內容撰寫人

常見問題（FAQ）#

收集常見問題（Frequently Asked Questions）並盡可能完善地回答。記得將問題和答案通用化與匿名化。FAQ 文件的格式很簡單：將問題以粗體呈現，答案放在下方。如果需要，可以加上「Q:」和「A:」前綴。

Figure 9.3: Facebook API FAQ page

收集常見問題清單的方法：

  • 每月與支援團隊開會，詢問最常見的工單是什麼
  • 瀏覽 Stack Overflow，尋找關於你的 API 被投票最多的問題
  • 與合作夥伴和銷售團隊交流，詢問他們最常聽到什麼問題
  • 邀請開發者透過頁面上的表單提交問題，為你的 FAQ 區塊增添內容

到達頁面（Landing Page）#

這是開發者瀏覽你的文件網站時應該看到的第一個頁面。它通常應包含以下區塊：

  • 簡短說明 API 的用途——說明開發者可以實作的使用情境或從 API 獲得的核心價值
  • 行動呼籲（call to action）——引導開發者到下一步。「Get Started」是很好的行動呼籲，附上 Getting Started 文件的連結
  • 關鍵資源、範例和工具的連結

你的開發者到達頁面有雙重目的：歡迎並導入新開發者，以及為回訪的開發者提供資源和持續支援。你可能需要與行銷或設計團隊合作，確保頁面對兩種受眾都有吸引力。

這個頁面極為重要，因為它提供了 API 的第一印象。開發者會快速瀏覽此頁面來判斷是否適合他們的需求，如果找不到想要的東西就會立刻離開。Slack 經歷了多次迭代，每次改進到達頁面的不同面向。Google 花了數週的時間進行使用者研究來優化其開發者入口網站。

Figure 9.4: Stripe's API landing page

確保你的到達頁面和其他關鍵頁面在搜尋引擎（如 Google）中具有高度可發現性。這將是開發者找到你的網站最常見的方式。

變更日誌（Changelog）#

隨著 API 的演進和成熟，我們建議你在開發者網站上維護一份變更日誌。在這個頁面上，你提供開發者以下資訊：

  • API 的更新消息
  • 即將到來的破壞性變更（breaking changes）的細節
  • 安全性和服務變更通知

GitHub Releases 讓建立變更日誌變得容易。可參考 Releases API 了解更多細節。

為頁面加入 RSS feed 能讓開發者訂閱變更日誌，在更新時收到通知。這是建立開發者與 API 保持同步的簡單管道。

Figure 9.5: Slack API changelog

API 的變更也可以透過電子郵件或 Twitter 公布（如果你能透過這些管道觸及你的開發者）。然而，一個專門的頁面讓開發者能看到自上次使用以來 API 經歷的所有變更，同樣非常有用。記住，不同的受眾偏好不同的溝通方式。

服務條款（Terms of Service）#

服務條款（ToS）是一份描述 API 合理使用方式的文件——什麼是允許的，更重要的是，什麼是不允許的。這份文件對想了解其使用情境是否被支援的開發者非常有用，對你作為 API 開發者設定使用邊界也至關重要。ToS 是執法的基準——對 API 濫用採取行動的依據。

ToS 應由你的法律顧問撰寫或至少審閱，應定義以下內容：

項目說明
速率限制（Rate limits）詳見第 6 章
資料保留政策（Data retention policy）開發者可以使用從你的 API 取得的資料多久、用於什麼目的？
隱私政策（Privacy policy）開發者可以對個人識別資訊（PII）做什麼？可以與誰分享？
不允許的使用情境（Non-allowed use cases）你的 API 可以用於商業用途嗎？可以用於成人或賭博用途嗎？
API 授權（API license）開發者可以轉售你的 API 嗎？可以作為他們 API 的一部分使用嗎？是否免費使用？
額外要求（Additional requirements）開發者是否需要在其應用中張貼隱私聲明？

在 ToS 中聲明你可以隨時間修改條款也很重要。隨著生態系統成長和 API 演進，你會發現需要更新 ToS 以適應新情況。當與濫用 API 的開發者溝通時，應引用他們違反的 ToS 條款，並與他們合作達成合規。

記住，要使 ToS 有效，它應該簡單且簡短。這是一份你實際上希望開發者閱讀和理解的法律文件，而非一個儀式化的勾選框。

範例與程式碼片段（Samples and Snippets）#

為開發者提供程式碼範例（code samples）和程式碼片段（snippets）是提升他們使用 API 的效率和生產力的好方法。當做得好的時候，你可以在範例中融入最佳實踐（如效能和安全性），讓開發者更不容易犯錯或濫用 API。

程式碼範例（Code Samples）#

程式碼範例可以有多種形式，但它們都遵循一個基本意圖：為開發者提供如何使用 API 的參考範例。你應該以開發者最常用的程式語言提供程式碼範例。程式碼應具有高可讀性，並包含大量註解來引導開發者理解每個 API 使用區段。

即使你只能提供單一的程式碼範例，只要它一致且基於核心開發原則，對所有背景的開發者都很有價值。PHP 和 Node.js 很適合作為 Web API 範例，因為它們容易聚焦在請求和回應循環上，無需引用額外的框架。

如同教學文件，程式碼範例也需要維護。當 API 變更時，你也需要更新所有範例。

程式碼範例的常見類型：

  • 單一使用情境範例——如發送訊息、取得事件或進行付款
  • 整合範例——展示 API 不同面向之間的整合，例如展示經過驗證的 API 請求，或結合兩個請求的回應來完成一個任務
  • 參考應用程式（Reference App）——處理的是商業使用情境而非展示特定 API 功能。好的例子包括 Google 每年發布的開源 Google I/O 應用，或 Twitch 內建在其範例中的聊天應用

參考應用程式的主要挑戰是讓它們具可讀性、可用性，且不與特定使用情境過度耦合。如果一個應用過度優化於某個使用情境，開發者就很難從中學習並推斷出自己需要實作的內容。

程式碼片段（Snippets）#

程式碼片段（Snippets）是簡短且具上下文的程式碼範例，用來搭配教學文件、參考文件或 FAQ 回答。程式碼片段應在個位數行數以內，需要簡要的文件說明但仍保持高可讀性。

與程式碼範例不同，片段是完整程式碼的一部分；你不需要在片段中宣告變數或加入 import。片段看起來應該像是從程式碼範例中剪下並貼到文件中的。

Figure 9.6: A code snippet example

因為片段更短且更容易實作，我們建議你以多種程式語言實作它們，讓開發者能直接剪貼到自己的程式碼中。

一個好方法是在文件中使用互動式語言切換器（language switcher），讓開發者選擇他們偏好的程式語言。

Figure 9.7: Firebase samples with language switcher

軟體開發套件與框架（SDKs and Frameworks）#

開發者有不同的熟練程度，並非所有人都能自在地直接存取你的 Web API。建立軟體開發套件（SDK）和框架（Framework）是讓 API 更容易使用的好方法。SDK 或框架的另一個好處是你可以將最佳實踐和安全措施直接內建其中，消除開發者自行實作這些實踐的需要。

專家建議：Ron Reiter 談 SDK

好的 API 在所有語言、平台和程式風格中都有 SDK 綁定。我學到的其中一個教訓是，你必須提前為極端使用情境做好準備，並確保你的 API 能滿足客戶的需求。

—— Ron Reiter，Oracle 工程資深總監

SDK#

SDK 是 API 上的薄抽象層（thin abstraction layer）。它們讓開發者能使用程式碼函式庫而非進行原始 API 呼叫。開發者下載或引用 SDK 函式庫，並透過呼叫 SDK 的功能來建構其商業邏輯。

許多公司用 SDK 包裝其 API，許多開發者也偏好使用 SDK 而非直接呼叫 API 方法。這是因為處理和發送 Web 請求本身就有其固有的複雜性。

SDK 的關鍵要點：

  • SDK 的介面需要可讀且有良好文件，但內部實作不需要——可以被優化甚至混淆和壓縮
  • 務必以開發者使用的程式語言提供 SDK——SDK 不像範例程式碼，它們可移植性較低，如果不是目標受眾的語言基本上毫無用處
  • 發布 SDK 後需要持續更新——在進行 API 更新的同時更新 SDK。如果你的開發者重度依賴 SDK 卻不更新，他們將無法存取你剛發布的新平台或 API 功能

將 SDK 的使用與直接 API 呼叫分開測量（instrument and measure）非常重要。建立和維護多個 SDK 既昂貴又費力。查看數據能給你一個好的指標，判斷是否需要繼續投入 SDK 的開發。

你可以使用 Swagger 等工具自動生成 SDK。雖然需要一些基礎設施工作（如為 API 加入 metadata），但這是在多種程式語言中生成 SDK 的簡易且高效的方式。

專家建議：Cloudinary 的 API 與 SDK

Cloudinary 的 API 是客戶除了管理 Web 控制台之外使用我們的主要方式。開發者建構涉及任何類型圖片和影片的網站和應用，使用我們來上傳、操作、管理和傳遞媒體。API 是 RESTful 的，並由眾多 SDK 包裝，幾乎支援任何程式語言。

—— Ran Rubinstein，Cloudinary 解決方案副總裁

框架（Frameworks）#

框架是你有時需要在 API 之上加入的額外抽象層。它們透過提供更接近開發者需要實作之使用情境的功能，讓使用 API 方法更加容易，並進一步隱藏 API 的複雜性。

案例：Botkit 框架

當 Slack 最初發布其 API 時，它提供了讀取和寫入訊息的基本功能。雖然這對經驗豐富的開發者來說已足夠建構 Slack 應用，但它並未提供建構對話式介面和機器人的簡易方式。開發者必須處理複雜的使用情境，例如在 Slack 中要求使用者輸入並等待答案透過 API 回傳。

Botkit 團隊開發了一個開源框架，封裝了該功能並將這些複雜使用情境的處理包裝在一個簡單易用的函式庫中：

controller.hears(
  ["hello", "hi", "greetings"],
  ["direct_mention", "mention", "direct_message"],
  function (bot, message) {
    bot.reply(message, "Hello!");
  }
);

在這個範例中，開發者聲明他們要透過 mention、direct mention 或 direct message 來聆聽 hello、hi 或 greetings，並以 Hello! 回覆。如果沒有 Botkit 框架，要完成這件事的程式碼複雜度將提高一個數量級。有了 Botkit，開發者只需定義商業流程，框架就會處理其餘所有事情。

何時需要框架：

  • 如果你的 API 簡單且直觀，你可能只需要提供程式碼範例或 SDK，將額外複雜度留給開發者，以降低維護成本
  • 考慮開發者的熟練程度——進階開發者可能不需要框架來處理複雜的使用情境

框架和 SDK 在正確維護時的優勢：

  • 提供更容易的 API 升級和遷移路徑——你可以抽象化 API 變更，讓開發者的舊程式碼繼續運作
  • 破壞性變更的負面影響較小——開發者只需替換 SDK 或框架的新版本
  • 開發者可以透過替換新版本的 SDK 或框架來輕鬆存取新 API 功能

建立 SDK 和框架時，務必讓它們在 API 網站上容易存取且容易被發現。我們也建議在 GitHub 等程式碼儲存庫中託管你的 SDK 和框架，讓開發者能受程式碼啟發、回報錯誤並貢獻程式碼。

開發工具（Development Tools）#

你的 API 對開發者來說很容易看起來像一個令人畏懼的黑盒子（black box）。提供正確的工具能大大幫助開發者自行解決問題。每個 API 都有不同的挑戰，雖然這裡涵蓋了一些常見的痛點，但你需要分析和理解開發者的需求與痛點，並為你的服務量身定制工具。

除錯與疑難排解（Debugging and Troubleshooting）#

即使有有意義的錯誤訊息，開發者仍然可能難以確切知道請求為何以及如何失敗。這就是為什麼提供分析、除錯和疑難排解 API 呼叫的工具非常有幫助。

除錯工具的形式從簡單到複雜：

  • 簡單：一個網頁，讓開發者查看與其 API 呼叫相關的日誌
  • 複雜：整合到開發環境中的逐步除錯器

在許多情況下，前者就足以排解大多數問題。

沙盒與 API 測試器（Sandboxes and API Testers）#

沙盒（Sandbox）和 API 測試器讓開發者能快速測試和驗證他們是否以正確的方式使用 API。

  • 沙盒提供開發者安全且隔離的環境——例如，一組模擬的圖片列表，開發者可以使用 API 隨意刪除和修改，而不用擔心更動到正式資料
  • API 測試器通常作為 API 文件的一部分，讓開發者測試 API 呼叫——有時使用真實資料。Google 提供了一個非常完整的 API 測試服務，稱為 APIs Explorer

Figure 9.8: Google's APIs Explorer

開發者使用 APIs Explorer 進行 API 請求時不需要撰寫程式碼；他們只需要提供有效的輸入參數。

多媒體資源（Rich Media）#

學習技術內容有很多方式——有人喜歡閱讀、有人喜歡聽、有人喜歡觀看。雖然許多開發者偏好書面教學和文件，但透過短片、網路研討會、線上 Q&A 等方式來吸引和教育開發者的趨勢正在成長。

影片（Videos）#

影片是介紹新技術、提供通用最佳實踐或深入探討主題的好方法。

現今製作影片並不困難——大多數手機和數位相機都能製作高畫質影片。許多開發者關係人員甚至在家中就能製作影片教學。

然而，製作高品質影片仍然可能昂貴且困難：

  • 需要專業設備、大量練習和多次排練
  • 在 Google 有一整個團隊專門負責編輯和製作影片
  • 站在鏡頭前呈現複雜的技術內容需要特定技能

表現最好的影片是短影片。超過兩分鐘的影片往往會有大幅的觀看率下降。

如果你滿足於中等品質的影片，錄製現場演講是一個很好的起點。每當你在活動中進行現場演示時，可以錄製下來並放在網站上供其他開發者觀看。

故事：Google 加倍投入影片

當 Amir Shevat 在 Google 工作時，團隊在一次超長的全球巡迴（在超過 12 個國家反覆呈現相同的內容）之後決定加倍投入影片。他們錄製了一些場次，發現錄影觸及的人數（以觀看次數衡量）比巡迴期間所有現場觀眾的總和還多。在那之後，他們建立了一整個團隊專門大規模製作高品質影片。

—— Amir Shevat

Office Hours#

Office Hours 是讓開發者獲得問題解答的好資源。這是你撥出的一段時間，專門回答問題並幫助開發者在你的 API 上進行開發。

當 Slack 開發者平台團隊剛成立時，規模非常小。團隊成員無法親自會見所有想要平台培訓的開發者，因此決定推出每週一次的線上 Office Hours。開發者和合作夥伴可以使用 Slack 提供的公開視訊通話連結加入，提出他們的問題。因為這些場次有多位參與者，額外的好處是每個人都能從彼此的問題中學習。

網路研討會與線上培訓（Webinars and Online Training）#

網路研討會（Webinar）是線上教育開發者的好方法。有些開發者偏好這種學習方式，因為它更具協作性。在網路研討會中，講者透過線上工具（如 Zoho）呈現主題，並邀請開發者加入培訓。演示會廣播給觀眾，有時伴隨螢幕分享或影片。在研討會結束時（有時甚至在進行中），開發者可以針對內容提問，講者會進行回答。

專家建議：Amir Shevat 談網路研討會

撰寫本書時，我每月舉辦一次關於我的上一本書《Designing Bots》（O’Reilly）的線上培訓。研討會歷時兩小時，參與者進行培訓和實作練習。我能在不離開辦公室的情況下與約 50 位開發者互動。

—— Amir Shevat

社群貢獻（Community Contribution）#

雖然本章中概述的所有資源都是教育、培訓和吸引開發者使用 API 的好方法，但建立所有這些資源是一項需要時間和金錢的艱鉅任務。好消息是——其中一些資源可以由使用你 API 的開發者社群來建立和維護。

蓬勃發展的開發者社群的正面附加效果之一是其成員會貢獻內容和產出資源。開發者撰寫教學文件、製作影片、分享程式碼範例並回答問題。以下是一些真實的例子：

  • Google 與社群中的關鍵成員（稱為 Google Developers Experts）合作，製作影片、演講和程式碼範例
  • Slack 管理開源 SDK，持續接收錯誤修復和程式碼修補。也在其開發者網站上列出社群文章
  • 行動開發者在世界各地聚會、分享見解並互相培訓。例如在以色列特拉維夫，一群社群成員建立了一個志工營運的課程 Android Academy，教育新開發者如何建構出色的 Android 應用
  • Twitch 使用公開論壇，讓開發者可以討論他們完成的工作、互相支援，並向 Twitch 開發者體驗產品團隊提供回饋

幾乎每個 API 都有一定程度的社群貢獻。但記住，你需要自己提供基本文件，因為在初期社群貢獻會很少。將社群貢獻視為你工作的補充，而非替代。

每當你使用社群貢獻的內容時，感謝貢獻者。他們為你做了無私的事，給予他們認可既是正確的做法，也是對其他想要貢獻的人的激勵。

在開發者網站上建立社群貢獻區塊是賦能開發者的好方法（當你有足夠的文章和程式碼範例時）。記住，社群貢獻的維護是更大的問題；如果你變更了 API，需要與貢獻者合作修改他們的內容，或明確標示每個貢獻適用的版本。

結語#

開發者資源在你的 API 之上增添了一層細膩且關鍵的價值。沒有開發者資源，你的受眾需要猜測如何使用你的 API，很可能會誤用它——或者更常見的情況是，根本不會使用它。

本章概述了常見的開發者資源並提供了建立它們的技巧。記住每個 API 都不同，你的開發者可能需要我們未明確涵蓋的額外資源。保持與開發者的聯繫、同理他們，並培養你的社群以建立自我維持的生態系統。

Backward 建立開發者生態系統策略 開發者計畫 Forward