一旦api發生變化，就可能對相關的呼叫者帶來巨大的代價，使用者需要排查所有呼叫的**，需要調整所有與之相關的部分，這些工作對他們來說都是額外的。如果辛辛苦苦完成這些以後，還發現了相關的bug，那對使用者的打擊就更大。如果api經常發生變化，使用者就會失去對提供方失去信心，從而也會影響目前的業務。
但是我們為什麼還要修改api呢？為了api看起來更加漂亮？為了提供更多功能？為了提供更好的效能？還是僅僅覺得到了改變了時候了？對於使用者來說，他們更願意使用乙個穩定但是看起來不那麼時髦的api，這並不意味著我們不再改進api了。當糟糕的api帶來的維護成本越來越大時，我想就是我們去重構它的時候。
如果可以回頭重新再做一遍，那麼我心目中的優秀的api應該是怎麼樣的？
判斷乙個api是否優秀，並不是簡單地根據第乙個版本給出判斷的，而是要看隨著時間的推移，該api是否還能存在，是否仍舊保持得不錯。槽糕的api介面各種各樣，但是好的api介面對於使用者來說必須滿足以下幾個點：
而對於開發人員來說，要求又是不一樣的：
如何做到以上幾點，以下是一些總結：
1、 面向用例設計
如果乙個api被廣泛使用了，那麼就不可能了解所有使用該api的使用者。如果設計者希望能夠設計出被廣泛使用的api，那麼必須站在使用者的角度來理解如何設計api庫，以及如何才能設計出這樣的api庫。
2、 採用良好的設計思路
在設計過程中，如果能按照下面的方式來進行設計，會讓這個api生命更長久
除此之外，下面還列出了一些具體的設計方法：
3、 避免極端的意見
在設計api的時候，一定要避免任何極端的意見，尤其是以下幾點：
4、 有效的api評審
api設計完成以後，需要經過周密的設計評審，評審的重點如下：
5、 提高api的可測試性
api需要是可測試的，測試不應依賴實現，測試充分的api，尤其是經過了嚴格的「相容性整合測試」的api，更能保證在公升級的過程中不出現相容性問題。相容性整合測試，是指一組測試用例集合，這組測試用例會站在使用者的立場上使用api。在api公升級以後，再檢測這組測試用例是否能完全符合預期的通過測試，盡可能的發現相容性問題。
6、 保證api的向後相容
對於每乙個api的設計者來說，都渴望做到「向後相容」，因為不管是現在的api使用者，還是潛在的api使用者，都只信任那些可相容的api。但向後相容有多個層次上的意義，而且不同層次的向後相容，也意味著不同的重要性和複雜度。
7、 保持逐步改善
過去我們總希望能將現有的「不合理」的設計完全推翻，然後按照現在「美好」的思路，重新設計這個api，但是在一段時間以後，又會碰到一樣的狀況，需要再推翻一次。 如果我們沒有有效的逐步改善的辦法，依靠推翻現有設計，重新設計api只能讓我們回到起點，然後重現之前的過程。 要有一套行之有效的持續改善的辦法來在api相容的同時，改善api使之更好。
8、 把握api的生命週期
每乙個api都是有生命週期的，我們需要讓api的生命週期更長，並且在api的生命週期結束時能讓其平滑的消亡。
開發api的過程其實就是乙個溝通交流的過程。溝通的雙方就是api使用者和api設計者。
9、 一些具體的實施方案
在乙個api不可避免要消亡或者改變的時候，我們應該接受並且面對這個事實，下面列舉了幾種保證相容性的前提下，對api進行調整的辦法：
一些好的api示例：
flickr api，這裡是文件的示例，同時提供了乙個非常方便的api測試工具。
mediawiki api
ebay api，這裡有乙個非常詳盡的文件示例。
在手機廣泛流行的今天，手機應用也隨之越來越多，而且成長的速度也非常快。手機應用軟體開發實現方式同普通pc軟體一樣，也分為bs和cs方式。而採用cs方式，在伺服器端大多採用介面的形式提供資料互動(主流資料互動方式有：json、webservice等)，今天要說的就是如何設計介面。
介面作為連通客戶端與資料庫進行資料流通的橋梁，起著舉足輕重的作用，直接影響著程式的效率性、穩定性、可靠性以及資料的正確性、完整性。客戶端注重的是介面美觀，操作方便順暢，是使用者最直接的感受體驗，而介面則是所有資料的提供者，是使用者深層的內涵體驗。
因次，設計介面在乙個專案中，是非常重要的。那麼我就目前的經驗總結下如何合理設計介面。
一、 設計原理
1. 深入了解需求
除了設計資料庫的人最了解需求外，其次就是設計介面的人了，甚至有時介面開發人員還要參與到資料庫設計中。從「客戶端-介面-資料庫」的層次上看，介面明顯扮演著承上啟下的角色，一方面要明白介面要什麼資料，另一方面要考慮如何從資料庫獲取、組織資料。所以如果不了解需求，你就無法正確抽象物件來組織資料給客戶端，也無法驗證資料庫的資料結構能否滿足需求。資料庫設計者要了解需求中的資料結構，而介面則更多的要了解需求中的邏輯結構以及由此衍生出的邏輯資料結構。
2. 了解資料庫結構
既然介面要明白如何從資料庫獲取、組織資料，就當然要了解資料庫結構啦。
3. 了解客戶端原型
了解原型，其實更多是為了幫助你設計介面時需要提供的資料和結構。但有時當你設計時並沒有原型，所以此條並不是必須要求的。但假如設計完介面後原型出來了，我們也可以拿原型還驗證介面設計是否正確、合理。
二、設計原則
1. 充分理由
不是隨便乙個功能就要有個介面，也不是隨便乙個需求就要加個介面。每新建乙個介面，就要有充分的理由和考慮，即這個介面的存在是十分有意義額價值的，無意義的介面不僅增加了維護的難度，更重要是對於程式的可控性的大大降低，介面也會十分臃腫。因此我放在了第一條。
2. 職責明確
乙個介面只負責乙個業務功能，它與設計模式裡的職責單一原則類似但卻不同，因為乙個業務功能裡可能會包含多個操作，比如查詢會員，可能除了查詢會員表外還要獲取該會員的其他必要資訊，但不要在查詢會員的同時還有修改許可權等類似的其他業務功能，應該分成兩個介面還做。
3. 高內聚低耦合
乙個介面要包含完整的業務功能，而不同介面之間的業務關聯要盡可能的小。還是查詢會員的例子，有時查詢會員的同時，可能該會員的相關資訊要隨之發生變化(如狀態)，如果這時一條完整的業務流水線，那麼就應該在乙個介面裡完成，而不應再單獨設立介面去操作完成。就是說乙個介面不應該隨著另乙個變化而變化或以某幾個介面為前提而存在。
4. 分析角度明確
設計介面分析的角度要統一明確。否則會造成介面結構的混亂。例如，不要一會以角色的角度設計，一會兒就要以功能的角度設計。
5. 入參格式統一
所有介面的引數格式要求及風格要統一，不要乙個介面引數是逗號分隔，另乙個就是陣列;不要乙個介面日期引數是x年x月x日風格，另乙個就是x-x-x。
6. 狀態及訊息
提供必要的介面呼叫狀態資訊。呼叫是否成功?如果失敗，那麼失敗的原因是什麼。這些必要的資訊必須要告訴給客戶端。
7. 控制資料量
乙個介面返回不應該包含過多的資料量，過多的資料量不僅處理複雜，對資料傳輸的壓力也非常大，會導致客戶端反應緩慢。過多的資料量很多時候都是介面劃分不明確。
8. 禁止隨意拓展引數
與第1條類似，只不過是針對引數而言了。日後拓展介面可能是難以避免的，但是不要隨意就加引數，加引數一定是必要且有意義的，需求改變前首先應考慮現有介面內部維護是否能滿足需求，而不要通過加個引數來方便自己實現需求的難度，因為引數的更變會直接導致客戶端呼叫的變化，容易產生版本相容性問題。
三、設計方法
1. 抽象業務
相比抽象物件而言，抽象業務更巨集觀，我覺得相對也容易一些，但抽象尺度往往不太好把握。
2. 資料格式
介面定義的資料格式必須都經過充分考慮，否則會出現資料轉換失敗或超出長度等錯誤。如果無法確定，直接設定成字串是最合適的。
3. 有意義的命名
無論是介面還是引數，名稱都應該是有意義的，讓人能看明白的。
總之，介面設計是乙個細緻的工作，設計時也會有很多矛盾，但個人傾向於粗粒度設計方向(即內聚性更高一些)，這樣不僅給客戶端瀏覽介面方便明確，維護也輕鬆些，這麼做的缺點就是某一介面擴充套件時不是很靈活，但可以通過重新定義乙個介面來彌補，但正如上所說，新增介面還是要三思而後行的。以上很多雖然都是理論性講解，但牢牢記住這些，並結合實際工作，就會慢慢深刻的體會到其中的含義。即理論指導實踐，實踐來驗證理論。
API 介面設計 原則
api 設計乙個非同步介面實踐 知乎 介面設計的16個原則 accident web api介面設計經驗總結 hugejihu9的專欄 csdn部落格 聊聊restful 介面設計篇 一 就浩這口 csdn部落格 api 介面設計問題 獲取所有資料 和 獲取我的資料 介面是分開的嗎 v2ex wha...
api介面設計
請求模式也可以說是動作 資料傳輸方式，通常我們在web中的form有get post兩種，而在http中，存在下發這幾種。get 選擇 從伺服器上獲取乙個具體的資源或者乙個資源列表。post 建立 在伺服器上建立乙個新的資源。put 更新 以整體的方式更新伺服器上的乙個資源。patch 更新 只更新...
API介面設計
請求模式也可以說是動作 資料傳輸方式，通常我們在web中的form有get post兩種，而在http中，存在下發這幾種。get 選擇 從伺服器上獲取乙個具體的資源或者乙個資源列表。post 建立 在伺服器上建立乙個新的資源。put 更新 以整體的方式更新伺服器上的乙個資源。patch 更新 只更新...