建置 API 很困難。除了與業務利害關係人進行漫長的會議、選擇正確的技術堆疊以及建置適當的資料分發模型之外，還有許多細節可能會被忽略。在 21 世紀偉大的 API 運動之後 — 隨著社群媒體的出現和行動技術採用的爆炸式成長 — 各組織已經意識到 API 所帶來的成長機會。
但請小心您的 API。 API 可以是您最好的朋友，但也可能是您最大的負擔。在取用您的 API 時，糟糕的使用者體驗將導致無休止的支援電話，隨之而來的是不良聲譽，而這一切都可能導致您的服務變得不可靠。因此，在您實際開始實作 API 之前，仔細規劃、規劃和再規劃非常重要。 這就是設計和 RESTful API 描述格式（如 OpenAPI 規格 和 API Blueprint）的驚人能力發揮作用的地方。
定義 API 設計
當我第一次聽到這個詞時，我認為它的意思是編寫語法和程式碼，使其具有美感。雖然這是一部分，但 API 設計涉及的不僅僅是您編寫語法的方式。設計 API 表示提供有效的介面，協助您的 API 消費者更好地了解、使用和整合它們，同時協助您有效地維護它們。每個產品都需要一份使用手冊，而您的 API 也不例外。 API 設計應包含：
- 資源的結構
- 您的資源文件
以上有許多良好的實務作法，我將在後續的部落格文章中介紹。現在，讓我們首先了解為何您的 API 應具有出色的設計的重要性。
有助於更好的實作
API 的設計是您的 API 想要實現的目標的堅實藍圖，並全面概述了與每個端點相關的所有端點和 CRUD 作業。 有效的 API 設計可以大大幫助實作，並防止複雜的組態、遵守類別內的命名架構，以及其他可能讓您熬夜數天的問題。設計過程也將幫助您仔細思考如何分發您的資料，以及您的核心產品將如何運作。
促進增量開發
API 開發是一個持續的過程。任何認為不是這樣的公司都沒有充分利用 API 的全部潛力。隨著您的產品和服務不斷發展，您的 API 也應該如此。擁有清晰的設計可協助您的組織和團隊確切了解哪些資源或子資源需要更新，從而防止混亂和混亂。 API 越大，管理起來就越困難。精心設計的 API 可以防止重複工作，並幫助開發人員確切了解哪些資源需要更新，以及哪些資源應該淘汰。
促進更好的文件
文件對於建置讓您的 API 被取用的介面至關重要。在許多情況下，只有在映射出 API 的資源和回應要求週期後，才會完成全面的文件。 穩固的初始結構使負責處理文件的人員可以更快、更少出錯地記錄 API。透過出色的設計，可以使文件流程更加自我最佳化，以便在之上建置全面的介面。
改善開發人員體驗
開發人員體驗 (DX) 至關重要。如果您是開發人員，您可能必須使用某個讓您想砸爛電腦的服務並與之整合。我們都經歷過這樣一個網路服務，讓我們在 StackOverflow 和 Reddit 上花費無數小時，試圖弄清楚如何使用它。 良好的 API 設計使最終開發人員的生活變得輕鬆。它易於理解，所有資源都井井有條，互動起來很有趣且賞心悅目，因此取用您 API 的人員可以獲得完美的使用體驗。
結論
良好的 API 設計可提高您的 API 的可用性，從而提高採用率、減少麻煩，並讓您的 API 工作獲得更好的成功機會。雖然我已經闡述了 API 設計的重要性，但將其付諸實踐可能很困難。有效的設計需要練習。在接下來的部落格文章中，我將嘗試說明一些設計 API 時的良好實務作法。
感謝您的閱讀！正在尋找更多 API 資源嗎？訂閱 Swagger 電子報。每月接收一封包含我們最佳 API 文章、訓練、教學課程等的電子郵件。