使用原型作為 API 產品規範

作為 SendGrid 的開發人員體驗產品經理，我的任務是識別涉及我們 API 的機會、功能和產品。 我一直在做的一件事是確定方法，以便更有效地將我的產品創意傳達給其他 PM、工程師和客戶。

我了解到，單一的產品需求文檔 (PRD) 是一種不太理想的方法，而包含與產品規範相同的信息的可測試接口將是一個強大的替代方案。 PRD 的問題在於它們通常非常大並且主要是文本。 失去自己的位置或錯過真正重要的事情太容易了。

我們在 UX 方面的朋友已經使用Invision等工具解決了這個問題，它們提供了一個您可以觸摸和使用的可點擊界面，而不是簡單描述界面的文檔或線框。 由於 API 是一個接口，我們需要一個允許與規范進行實時交互的工具，而不是文檔中的一堆描述性文本和 JSON。

定義要求

這個作為產品規範的可測試接口應該是什麼樣的？ 它將如何運作？ 它存在嗎？

在閱讀 Marty Cagan 的《靈感：如何打造客戶喜愛的產品》的第 18 章“重塑產品規範”時，我意識到我想分享一個我一直在使用的工具，它可以滿足 Cagan 對產品規範的要求，其中大部分他的產品規格願望清單，以及我自己的原型作為規格要求的個人清單。

卡根的要求*：

• 規範必須描述完整的用戶體驗。
• 規範必須準確地代表軟件的行為。
• 您必須能夠以所有利益相關者都能得到他們需要的方式來傳達產品。
• 規格會改變
• 規範需要有一個單一的主表示，以減少歧義和版本問題。

卡根的願望清單*：

• 您將需要補充原型 [with]：
  • 商業邏輯
  • 發布要求
  • 平台交付要求
  • 用例
• 我真的很想能夠註釋原型

我對原型規範的要求：

• 原型應該是規範。
• 文檔應該集成到原型中。
• 公司中需要它的每個人都應該可以訪問原型和文檔。
• 客戶應該能夠訪問原型的功能部分以進行用戶測試。
• 原型應該取代規範並儘可能接近預期功能，而無需連接成品。
• 對原型進行更改和記錄應該很容易。
• 製作 A/B 變體應該很容易，任何可以訪問原型的人都可以對其進行測試。
• 從原型中導出客戶文檔應該很容易。

介紹停車燈

我一直在使用的幾乎可以滿足上述所有要求的工具稱為Stoplight.io 。 它的核心是 API 文檔引擎和 Web 代理。 它允許您使用直觀的 UI 定義您的 API，該 UI 在幕後將 Swagger 和 RAML 的精華作為其規範引擎，並能夠從任一格式導入或導出。

由於 StopLight 是一個文檔工具，您可以為您的端點定義請求、響應、標頭和描述。 使用代理功能，您可以調用您的 API 並驗證您的調用是否符合您的規範或自動發現您的端點以自動編寫大部分文檔。

StopLight 的代理還有其他幾個絕對令人驚嘆的功能：

• 如果您的產品未完成或您不想代理您的請求，則能夠對您的端點進行模擬調用。
• 用於在您的機器上測試原型的本地服務器。
• 用於在 Internet 上測試您的原型的遠程服務器。
• 中間件，用 Javascript 編寫，用於定義可以在調用原型端點之前和/或之後運行的代碼。

如果您將我的願望清單、Cagan 的規範要求和他的願望清單與 StopLight 提供的功能進行比較，您會發現 StopLight 滿足了所有需求和願望：

• 原型及其功能的內部文檔。
• 一個易於訪問的完整功能原型。
• 一個可測試的界面，能夠為用戶測試和反饋切換可變功能。
• 一種針對特定對話對原型進行版本控制的簡單方法，以便您可以近乎實時地修改原型的功能，以說明和驗證您收到的反饋。

StopLight 中的工作流程很簡單，任何人都可以完成，無論他們的技術能力如何：

• 創建一個新項目。
• 通過單擊並鍵入有關端點、其參數、請求和響應的信息來添加規範。
• 在定義屏幕中添加有關您的原型的規範信息。
• 如果您有可選功能，請使用中間件添加它們。
• 開啟嘲諷。
• 複製/粘貼模擬服務器的公共 URL 並分享它以獲取反饋。

如果您正在拜訪客戶並想實時試驗原型，只需將定義下載到您的計算機，創建一個以您的拜訪命名的新項目，然後導入定義。 現在您可以在不更改原始原型的情況下更改任何您想要的東西。 當您返回並合併想法時，進行更改就像最初構建原型一樣容易。

作為開發人員體驗產品經理，StopLight 不僅幫助我更有效地完成工作，而且使用起來非常簡單，並且由於文檔在客戶驗證步驟之前開始並更新，因此使記錄 API 的交付準備步驟變得容易在整個過程中。 StopLight 提供了許多其他用例和功能，但這可能是對我的工作影響最大的一個。

*Cagan 的要求和願望清單直接引用自Inspired: How to Build Products Customers Love。