API 設計 — 優化團隊的 API 設計流程
2024年11月7日
在之前 API 設計的文章，我們談了 API 設計 — 好的 API 設計有什麼特點？、API 設計 — 如何設計穩定可相容的 API。
而在這篇文章中，我們將把視角轉換到資深工程師的角度，來談假如今天你想邁向資深工程師，想要讓團隊整體的 API 品質可以提升，該如何做到?
我們將會從 API 設計流程、API 設計指南，以及文件化等要點切入。推薦讀者可以在讀的同時，思考目前所在的團隊，有沒有某個面向可以優化，並試著推動改善。（完整內容收錄在 E+ 成長計畫當中）。
API 設計流程
在談 API 設計流程前，推薦讀者自己可以先想一下，在設計 API 時該有哪些階段? 為什麼需要有這些步驟?
探索需求
在回答這個問題前，推薦讀者們可以回到本質來思考，API 的存在目的，是為了服務使用 API 的人，幫忙提供某個功能或解決某個問題。因此，API 設計的流程中，最推薦從需求開始。
從需求開始意味著需要取了解使用者、了解使用情境 (use cases)，而要做到這件事的最簡單方法，就是去找使用者聊、去與使用者互動。Stripe 前技術長 David Singleton 以及現任 Amazon 技術長 Werner Vogels 都表達過類似的觀點。
以 Stripe 來說，前技術長 David Singleton 分享過一個原則，那就是從使用者的角度反過來開發 API (working backward from the consumer of the API)。換句話說，在開發 API 前，會先去深入了解使用者的需求，然後才進行開發，而不是直接從開發者的角度思考後就開發。
具體來說，Stripe 的 API 開發者會參與使用者研究，甚至會坐下來實際跟使用 API 的使用者一起串接 API，然後在過程中觀察 API 的使用者有遇到什麼困難，在過程中持續收集回饋。David Singleton 談到在正式發佈 API 前，通常會經過幾輪的迭代與調整。
更進一步說，從使用者的角度反過來開發 API，也代表在實作前就先把背後還沒有實際功能的 API，讓使用者試接看看，來了解這樣的設計，使用者實際用起來好不好懂、會不會用錯。這能夠避免，如果已經實作好功能後，才發現設計上不好用、有沒考慮到的面向，那這樣就白費那些實作的時間。
雖說要去了解使用者的需求，不過要特別注意，跟使用者互動的過程中，不要直接按照使用者說的做。因為很多時候，使用者看的角度只有眼前所見的範疇，但 API 設計者應該要想更遠，要去深入思考使用者的表層需求底下，真正的根本需求是什麼。
總的來說，了解需求是 API 能否設計好的關鍵，假如目前所在的團隊，在實際設計 API 前，沒有針對使用者有完整的研究流程，推薦可以試著在團隊中導入。
設計
在了解完使用者的需求後，理論上 API 設計者會清楚知道：
- 使用者希望透過 API 做到什麼 (能夠回答為什麼使用者需要這個 API)?
- 什麼樣的設計會讓使用者覺得簡單好用 (能夠回答如何設計這個 API)?
如果沒辦法回答這兩個問題，推薦先不要進到設計階段，不然很可能之後要重頭來過，浪費寶貴的時間。
如果能清楚回答上述的兩個問題，接著會進入 API 的設計階段。在設計階段，會根據在前一階段收斂出的要點，來進行 API 設計。這時會需要詳細定義出 API 的規格、用什麼風格、會如何測試等等。
在這個階段，除了 API 的開發團隊外，推薦盡可能有跨團隊的角色加入，來給予開發團隊回饋。
舉例來說，目前業界建制比較完整的團隊，通常在這個階段，會找平台工程 (platform engineering)、開發者體驗 (developer experience)、安全性 (security) 相關的團隊，來給予設計上的回饋。這樣可以確保除了功能需求有做到外，重要的非功能需求也能照顧到。
因此，假如你想要讓團隊的 API 設計整體品質提升，推薦可以試著為團隊建立評論小組，去找尋公司內不同的技術專家，主動邀請他們給團隊不同面向的回饋。
閱讀更多
如果你對優化團隊的 API 設計流程等內容感興趣，我們在 E+ 有更深入的討論，會討論 API 測試、API 設計指南、API 文件化等議題。有興趣的讀者，歡迎加入 E+ 成長計畫。，
本文為 E+ 成長計畫的深度內容，截取前三分之一開放免費閱讀。歡迎加入 E+ 成長計畫閱讀完整版本 (點此了解 E+ 的詳細介紹)