設計優秀API七大要訣

英文原文：What makes a good API great?

一個超棒的 API 必定經過一番精心設計，肯花大量時間、站在用戶角度思考問題，這樣用戶使用起來才會事半功倍。那么，這樣的 API 需要具備什么樣的條件呢？

有的放矢

APIs 不單單是程序的復制品。它是在我們的核心應用不能解決問題時，擔當數據分析的角色。

如果一味追求“做到所有想做的”，那么我們的 APIs 可能會因此變得臃腫而過于復雜。所以好的 API 必須追求用戶體驗，有切實可行的目標。

追求極簡

如果一款應用的某個功能一時是A一時是B，那么用戶將會給逼瘋的。Dropbox 核心 API 在簡化這方面就做得不錯。其面向的操作對象是單一的，提供了讀取 metadata，讀取/下載數據共三個操作。開發者可以方便地使用它來進行二次開發，做出功能更豐富的應用。

簡易的說明

簡明扼要的文檔能讓用戶在短時間內掌握相關的使用方法，縮短開發用時，比方說 Github 提供的使用說明。這些將能有助于用戶了解不同的使用場合，從而更有信心地創建更復雜的應用。

支持 OAuth2 協議

OAuth2.0 是 OAuth 協議的下一版本，更關注客戶端開發者的簡易性。想象下如果登錄程序時，用戶不僅需要用戶名/密碼還得需要安全令牌，那么難道你不想立馬換一個程序嗎？

事實上，目前幾乎所有的 API 都是這樣做的。因此用戶不得不花費多余的時間來完成用戶認證。認證是需要的，但用戶可不這樣想。所以不妨參考下 OAuth2 規范對此作出改善。

多權限設置

當用戶被要求對第三方應用進行權限認證時，考慮最多的一個問題是：這對于我的個人數據有什么影響？

很多時候，答案是所有權限，這難免會讓用戶覺得存在風險。GoogleDrive API 做得就不錯，它允許開發者對權限進行管理。這樣做出的程序會讓用戶感覺舒服。

清晰的錯誤或無誤信息反饋

開發者在使用 API 過程中可能會出現錯誤，或許是不熟悉，或許是收到了限制；無論是什么，我們建議，以 HTTP 錯誤代碼形式加以說明。

及時的、清晰的反饋有助于用戶明白錯誤的來龍去脈。HTTP 錯誤碼一般不會引起歧義并含有清晰的錯誤闡述，所以建議由此入手。

提供變更檢測機制

APIs 一般是透過 internet 進行訪問，如果不對每個調用進行檢測，那么很有可能會加重服務器和用戶帶寬的負擔。因此使用合理的變更檢測機制(如 ETags)進行檢測是很有必要的。

以上所說的或許看起來比較基礎，但是我們應該引起重視；堅持從源頭抓起，從小處著手，才能做出最終讓用戶滿意的作品。

來自：http://news.cnblogs.com/n/513579/