建構API很難。除了需要和業務相關者進行長時間的讨論，選擇合适的技術棧已經建構合适的資料分發模型外，還有許多細節可以忽略不計。在21世紀偉大的API運動之後 - 随着社交媒體的出現和移動技術的普及，組織已經意識到API的增長機會。
但你要注意你的API。它可能是你最好的朋友，也可能成為你最大的負擔。在使用API時，糟糕的使用者體驗将導緻無休止的服務支援甚至是扯皮，接着聲譽就會敗壞，這一切将導緻你的服務不可靠。是以，在實際開始實施API之前，進行更多計劃，規劃和計劃非常重要。這就是RESTful API描述格式的設計和驚人的實力，如OpenAPI規範和API藍圖。
定義API設計
當我第一次聽到這個詞的時候，我以為它的意思是用一種美觀的方式來編寫文法和代碼。雖然這是一部分，但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設計的重要性，但實踐起來卻很困難。高效的設計需要實踐。
原文：What is API Design
轉載于:https://my.oschina.net/u/2422879/blog/2051863