一個 API-First 設計應該具有可複用性、互操作性、可修改性、用户友好性、安全性、高效性、務實性，並且重要的是，與組織目標保持一致。這些基本特徵將確保 API 能夠有效地為 API- First 組織戰略和開發模式做出貢獻，在這種模式中，API 可以最大限度地為業務創造價值。
但如何生成這樣的 API-First 設計呢？
在本文中，我們將探討如何通過以下五個流程集成到 API 設計過程中來實現 API-First 設計：
- 使用自然語言來分析和應對需求
- 觀察上下文並確定約束條件
- 充分描述和記錄 API
- 利用現有的 API 和指南
- 將自動化和人工反饋循環集成到流程中
1. 使用自然語言來分析和應對需求
為了確保創建的 API 符合組織的目標，需要使用自然語言深入分析需求。這種分析可能涉及明確消費者或最終用户、他們的用例以及如何實現它們，這對於確定滿足需求所必需的每個 API 功能至關重要。進行分析後，應與利益相關者交流預期，以確保一致性。
在進行此類分析時，只能使用自然語言，不考慮編程接口表示，通過這樣區分問題將有助於與專家討論，並避免過早地就諸如/customers or /customer或PUT or POST之類的問題展開辯論。最終，你可能會意識到有比標準 REST API 更好的選擇，例如，gRPC、異步或 GraphQL API 可能更適合。
2. 觀察上下文並確定約束條件
API 設計者和利益相關者必須觀察 API 上下文，並確定所有約束條件以確保 API 設計實用、高效且安全。這可能涉及到以下問題：
- 新 API 應該在什麼時候部署？
- 底層系統是否存在限制？
- 主題內容是否符合我們創建 API 的常用方法？
- 安全要求是什麼？
接下來，API 設計者和利益相關者可以決定是隱藏還是將約束條件融入設計中。隱藏它們可能會帶來額外的工作，但設計更好。另一方面，將它們納入其中可能會降低 API 的質量，但更容易按期交付。然而，請務必記住安全性是一個不可妥協的問題。
3. 全面描述和編寫 API 文檔
在設計過程中寫好 API 文檔至關重要，以確保捕獲所有信息，如編程接口描述、需求及其分析、約束和安全要求。這也可以指導你創建合適的 API。
為了描述和記錄 API，你可以輕鬆地使用諸如 OpenAPI、AsyncAPI、GraphQL schema 或 JSON Schema 等 API 規範。這些規範將為你提供一個框架，但它們只能用於記錄 API 的元素，而不是消費者如何組合它們以實現在需求分析期間確定的用例。
無論你使用哪種格式，把需求分析和生成 API 連接起來至關重要，以確保最終設計中不會遺漏任何內容。同時還需要向實施者提供儘可能多的信息，確保實現符合預期，例如，在 OpenAPI 文檔中， 你可以通過查看摘要來確認在需求分析過程中確定“搜索客户”的操作已轉換成 GET /customers 。此外，還可以查看操作安全配置及響應描述，以確保僅返回用户或消費者範圍內的客户。
4. 利用現有 API 和指南簡化決策過程
API 設計過程涉及到大量的決策。然而許多決策是相同的，因為所有的 API 最終都要處理相同的基本問題，例如，表示日期或金額的最佳方式、如何搜索目錄、創建資源或啓動流程等。此外，在一個組織內部，所有 API 必須具有共同的樣式。
為了避免在漫長且重複性高的討論中浪費時間或重新設計輪子，可以參考組織內其他 API 並複製它們的設計模式。不過，在描述常見“配方”，如“如何設計搜索操作”或者“如何管理文件上傳”的指南中，更高效的方法是將這些模式形式化。API 指南可以涵蓋各種主題， 從用户友好性到安全性， 但它們只作用於促進創建 API-First 設計。如果某個指導原則規定對實現該目標沒有幫助，就刪除它。
遵循指南能夠快速實現具有一定用户友好性、互操作性、可擴展能力、安全性和效率的 API 設計，但最重要的是可以幫助你專注於核心問題，創建正確的 API，而不會浪費時間和精力在遣詞造句問題上。
5. 將反饋循環整合到流程中
即使指南涵蓋了所有相關主題，並以友好的方式呈現，但總有一些 API 設計者可能永遠不會看，其他相關的人可能會通過反覆檢查指南中的細節而減緩進程。此外，任何人在編程接口設計中都可能犯一些小錯誤。因此，儘早尋求同事、專家和消費者的迭代反饋至關重要，與他們共享擴展的 API 文檔以及模擬數據，確保他們能獲取到所需的信息，以提供建設性的有效反饋。
Eolink 就是一個 API-first 的優秀案例，設計和開發了一系列的 API 工具平台，包括 API 快速生產、研發管理、自動化測試、網關、監控、開放平台等，實現對 API 的全生命週期覆蓋。首創提出 DTDD（文檔與測試驅動開發 ）理念，通過標準化的工具和流程來解決 API 迭代效率的問題，致力於讓 API 管理更簡單。
DTDD （ 文檔與測試驅動開發 ）：
文檔驅動開發：項目開發前，先把文檔寫好，明確功能需求、入參出參定義、異常情況處理等，再進行開發。
測試驅動開發：項目開發前，先寫好測試方案/用例，要求代碼順利通過測試，如不通過則持續進行改進。
