[ADP-51] API 審查

reviewing phase 1

這篇文章還沒有明確的說明怎麼審查一份 API 文件。

指導原則

審查範圍

• 應該(SHOULD)審查 API 的整體設計、資源模型、端點結構和命名約定。
• 可以(MAY)審查安全性考慮、錯誤處理和文件。
• 不應(SHOULD NOT)過度關注實現細節，除非它們直接影響公共 API 介面。
• 應該(SHOULD)在 ADP 網站中尋找設計模式。

審查標準

• 應該(SHOULD)評估 API 是否遵循 API 設計原則和最佳實踐。
• 可以(MAY)考慮 API 的可用性、一致性和可擴展性。
• 應該(SHOULD)驗證 API 是否實現其預期目的並滿足目標受眾的需求。

反饋風格

• 應該(SHOULD)提供具體、可操作的反饋，而不是一般性批評。
• 可以(MAY)使用建議性語言，如"考慮"或"可能"，而不是命令性語言。
• 應該(SHOULD)在指出問題和認可良好設計決策之間取得平衡。

解決分歧

• 應該(SHOULD)通過公開討論解決分歧，重點關注最終用戶需求。
• 如果無法達成共識，可以(MAY)尋求更高層決策者的意見。

審查評論示例

以下是符合這些指導原則的一些審查評論示例:

1. "考慮使用更具描述性的資源名稱。'items' 可能過於模糊；我們能否探索更精確的術語？"

2. "這個端點的回應結構看起來很清晰。你可能想考慮添加分頁支持，以便將來處理可能的大型數據集。"

3. "認證方法看起來合適。我們可能需要討論如何處理不同用戶角色的授權。"

常見問題

誰通常設計 API，如何設計？

API 設計是一項涉及軟體架構師、開發人員、產品經理和領域專家等利益相關者的協作努力。該過程通常從識別需求、目標、目標受眾、目的和約束開始。設計技術可能包括領域驅動設計、RESTful 原則或 GraphQL 架構設計。

我的 API 需要審查嗎？

• COMPONENT_INTERNAL API（團隊特定）：團隊外無需額外審查。
• BUSINESS_UNIT_INTERNAL API（組織特定）：建議由組織的技術負責人審查。
• COMPANY_INTERNAL API（公司範圍）：預期由 API 設計原則專家審查。
• PARTNER_EXTERNAL API（特定合作夥伴）：建議在設計過程中盡可能滿足更多原則，並且與合作對象確認 API 是否滿足其需要。
• PUBLIC_EXTERNAL API（非特定）：強烈建議在公開發布前進行審查。

誰應該成為 API 審查員？

API 審查員應具備 API 設計和最佳實踐的專業知識，了解組織的 API 設計原則，並能夠就各種 API 方面提供有價值的反饋。

如果 URL 設計難以決定怎麼辦？

讓 API 審查員參與決策過程。他們可以根據設計原則、最佳實踐和目標受眾需求提供指導。

如何確保多個 API 之間的一致性？

參考本站以獲取全面的指導方針和最佳實踐，以維持 API 設計的統一性。

如果我的 API 設計案例未被任何 ADP 涵蓋怎麼辦？

如果您的特定 API 設計案例未被現有的 ADP（API 設計原則）涵蓋：

• 諮詢您的團隊 Tech leader 和 API 治理專家，以確定最佳方法。
• 記錄您的決策過程和理由。
• 如果該案例可能在未來項目中再次出現，考慮提出新的 ADP。請見 ADP-3。
• 確保您的解決方案與一般 API 設計最佳實踐和組織的整體 API 策略保持一致。

我可以建立團隊特定的原則嗎？

是的，團隊可以建立特定的原則，但需要考慮以下幾點：

• 團隊特定的原則不應與組織範圍的 ADP 相矛盾。
• 它們應該在團隊內明確記錄和溝通。
• 考慮這些原則是否對其他團隊或整個組織有價值。
• 定期審查和更新團隊特定的原則，以確保它們保持相關性並與更廣泛的組織目標保持一致。

如果我需要違反標準怎麼辦？

如果您需要違反既定的 API 設計標準：

• 清楚記錄違反的原因及其潛在影響。
• 尋求 API 治理利益相關者(stakeholder)或相關決策者的批准。
• 考慮這種違反是否表明需要修訂或擴展現有標準。
• 將非標準解決方案作為例外實施，而不是新規則。
• 如果可能，計劃未來與標準保持一致。
• 確保違反不會損害 API 的安全性、可擴展性或可維護性。