[ADP-0] ADP 概覽
本 ADP 是與 ADP 概覽設計相關的 ADP 類別。
- ADP 編號：0000-0020 保留給 ADP 相關的 ADP。
什麼是 ADP？
ADP 意即： API 設計原則（API Design Principle）；一個較為全面的 API 設計慣例、指導、最佳實踐和改進提案的集合。主要目的是把 API 設計標準化，確保不論是組織內部以及公司不同組織之間 API 的一致性。關於更多設計理念請參見ADP 目的。
在設計 API 時，開發者經常面臨許多決策場景。有時候我們需要在實務與理論上找到平衡點，更多時候我們需要有明確的參考依據，以確定“某件事情應該如何進行”。
有些設計規範已經有了 RFC 標準可以遵循，但有些可能仍在草案階段。我們將盡力研究任何與 API 設計相關的規範或慣例，提供明確的準則作為參考。
大體上所有 API 設計會牽涉到的方向都有一個以上的既有解決方案，但可能仍然有所不足。ADP理論上會持續改進。
ADP 目前使用 markdown 檔案進行撰寫，並且在 github 上維護。文件的展示介面採用 vitepress。
為什麼要製作這個站點？
本站點的創建靈感主要來自 Zalando 和 OTTO 的 API 規範，以及 Google 的 AIP 網站。(請見本文參考資料段落。)
根據這些網站，設計者並未將 ADP 設計為與特定實際產品緊密結合（不過，域名相關的部分會涉及公司註冊的網域）。
因此，ADP 原則上可以作為任何 API 設計者在設計 API 時的參考資料，類似於 Google AIP 中所提到的。
為什麼不直接使用 Zalando/OTTO/Google AIP 的內容作為設計規範？
部分內容不適用於公司的現況
有些內容未能與時俱進
為什麼 ADP 是一個公開站點而非 confluence pages ?
- API 設計本身應該是無關乎機敏或商業邏輯，它更像是一種前端和後端之間的通用語言。語言的目的是溝通，溝通不應該在秘密中進行。
- 本站的設計者認為，公開 API 設計規範可以提高公司在軟體服務方面的信任度和整體品質，促進 API as a product 的理念發酵。
- ADP 是為了能夠簡單地通過分享網址（例如直接將 ADP-20 傳給 API 合作方用以取得 API 契約設計共識）以方便交流 API 設計理念而設計的。
API lint for ADP
目前 ADP 採用 redocly 作為 API lint 工具，並針對部分可程式化的規則做了客製化規則集。安裝使用請見API Lint。
如果我不遵循 ADP 會怎樣？
請參考 FAQ。
如何使用 ADP？
要有效地使用 ADP：
使用頂部搜索框：輸入與您當前設計問題相關的關鍵字。例如，如果您正在設計錯誤回應，搜索「錯誤處理」或「狀態碼」。
瀏覽完整的 ADP 列表：點擊右上角的列表鏈接以瀏覽所有可用的 ADP。
按類別探索：使用左側導航欄查找按主題分組的 ADP，如「身份驗證」、「版本控制」或「性能」。
應用到您的工作中：在面臨設計決策時，查閱相關的 ADP。例如，如果您正在設計一個新的端點，查看與 URL 結構和 HTTP 方法相關的 ADP。
請記住，ADP 是一個指南，而不是嚴格的規則書。使用它來為您的決策提供參考，並改進您的 API 設計。
聯絡 ADP 設計者
目前 ADP 整體包含文件跟工具由 Alive.Kuo 負責維護。
參考
本文件的靈感來源: