【翻譯】Win with APIs by keeping it simple

#Win with APIs by keeping it simple

原文：Win with APIs by keeping it simple

譯文Github地址:Win with APIs by keeping it simple

少便是多

##簡單易懂

就像你不須要閱讀使用手冊就知道如何使用 iPhone 同樣，一個好的 API 也不須要你先花上數天時間來摸清如何使用 API，而後才能展開工做。

做爲開發者，不論你對 Facebook 自己或褒或貶，有一點不能否認，它的 API 設計很是直觀和簡單：一旦你經過了認證，接下里的事情就水到渠成了。

在瀏覽器裏面輸入 https://graph.facebook.com/534822875 ，就能夠獲得 ID 爲 534822875 的用戶信息，JSON 片斷以下【譯者注：這個可能與實際結果有出入，一切以原文爲準】：

{
   "id": "534822875",
   "location": {
       "id": "114952118516947",
       "name": "San Francisco, California"
   }
}

Facebook 還建立了一個簡寫形式：using /me 來表示當前已經登錄的用戶，也就是說，https://graph.facebook.com/me 能夠獲得和上面同樣的結果。【譯者注：這個須要登錄以後纔能有結果，因此，實驗結果根據登錄狀態和用戶 ID 的不一樣而不一樣】

事實上，我經過本身在使用 Facebook 的功能（friends, photos, likes）時瞭解到的信息，幾乎就能夠猜到各個功能對應 API 的功能和方法名稱了。

好比，https://graph.facebook.com/me/likes 返回我在 Facebook 上的喜愛列表：

{
   "data": [
       {
           "category": "Media/news/publishing",
           "name": "The Guardian",
           "created_time": "2014-08-01T01:32:17+0000",
           "id": "10513336322"
       },
       {
           "category": "Movie",
           "name": "The Lives of Others Movie",
           "created_time": "2014-07-31T15:47:14+0000",
           "id": "586512998126448"
       }
   ],...
}

這個 API 很是直觀，基本上就能猜到裏面的有效資源字段名稱。

那如何得到個人照片列表呢？

沒錯，就是：https://graph.facebook.com/me/photos

一樣是獲取照片列表，Flickr 的 API 是這樣的：

https://api.flickr.com/services/rest/?method=flickr.people.getPhotos

人們能夠有無數對 Flickr API 的吐槽：好比「不是 RESTful 風格」等等。可是，最重要的問題仍是：不夠簡單。 既不直觀，也不容易記憶，更不容易理解。做爲一個使用者，我老是須要回過頭去對照 API 文檔來使用，這一點阻礙了他的使用體驗。

對照來看，Facebook 的 API 就簡單直觀得多，能夠快速上手並當即開工。這也是爲何會有超過 2 萬的開發者使用 Facebook 的 API 建立了超過 1百萬 app 的緣由。

##簡單易用

使用 RESTful 的方式來構建API，能夠幫助你遵循「理解簡單」的原則，也意味着你能夠像瀏覽器同樣來處理 http 資源。 這會幫助你將 API 構建在實際的項目和業務關係上，當你在談論 API 的時候，能夠緊密的關聯到員工，客戶和用戶所談論的業務上，這將是一個巨大的好處。

下面的 RESTful 風格 API，經過它能夠獲取帳戶列表或者某個特定的帳戶信息：

# 列出全部帳戶
GET /accounts

# 顯示帳戶信息
GET /accounts/{account-number}

下面的 API 構建在一個真實的生活場景之上，其返回一個特定帳戶的信息：

GET /accounts/6242525/balance

你能夠想象這樣的場景，某個客戶打電話過來問：個人帳戶號碼是6242525，你能幫我查一下個人帳戶餘額嗎？

經過這種方式，就至關於用一種通用而富有表現力的語言在你的 API 和業務之間創建了一種映射，使得用戶更容易理解。 使用 RESTful 的另外一個好處是，能夠方便的在瀏覽器中使用，實驗驗證也相對簡單。

#數據格式簡單

這麼些年，開發者們已經厭倦了冗長的XML等格式。他們再也不願意編寫自定義的解析器，轉而尋求更輕量級的選擇。JSON解決了這些問題，而且 JSON 正成爲一個事實上的數據交換格式。 另外，像許多 API 用戶同樣，若是你在使用JavaScript，那麼就可以很容易的集成JSON。

JSON是簡單的鍵值對錶。看看前面的例子，你能夠看到，我喜歡「Guardian newspaper」，點贊時間是「2014年8月1日」

{
   "category": "Media/news/publishing",
   "name": "The Guardian",
   "created_time": "2014-08-01T01:32:17+0000",
   "id": "10513336322"
}

##API 導航

經過提供分頁連接，導航 API 就很容易實現了，API能夠直接告訴用戶下一步的目標在哪，而無需用戶去手動構建通往下一步的 URL，這一點在處理大型數據集方面顯得特別重要。 如下是來自 Facebook’s Open Graph API 的優秀例子：其中全部響應都含有一個「paging」屬性，它告訴用戶在哪裏能夠獲得上一個或下一個數據集。另外一個好處就是，機器人或爬蟲能夠經過一樣的方式來瀏覽你的API。

{
   "paging": {
       "previous": "https://graph.facebook.com/me/albums?limit=5&before=NITQw",
       "next": "https://graph.facebook.com/me/albums?limit=5&after=MAwDE"
   }
}

##擴展用法

讓用戶可以控制 API 的行爲是一個強大的特性。有不少方法能夠作到這一點，包括使用各類排序規則，搜索和過濾。 「字段過濾」就能夠用來指定響應中應該包含哪些字段。這種特性在帶寬或性能受限，或者其中用戶只關心響應中的部分字段的狀況下特別有用。 過濾的另外一個好處是，將選擇交給用戶，讓用戶告訴 API 什麼是他們關心的，從而使得 API 的建立者沒必要針對每一種需求來開發不一樣的 API。

https://graph.facebook.com/me/likes?fields=category,name

上面的 API 調用告訴 API 在響應中只須要返回 「category」 和 「name」 字段便可。

{
   "category": "Media/news/publishing",
   "name": "The Guardian",
}

##維護簡單

全部的API須要支持向後兼容，同時它也應該給用戶提供一種只使用某個特定的版本的方法。要作到這一點，最簡單的方法是在基礎 URI 中包含版本號，而後默認不包含版本號的 URI 做爲最新的API版本。這樣作就給 API 用戶一個使用特定版本或者最新版本 API 的選擇餘地。

versioning （選擇版本）

/api/v1.0/accounts/12345 /api/v1.1/accounts/12345 /api/v2.0/accounts/12345

alias no-version to the latest version（最新版本）

/api/accounts/12345

API 的建立者須要當心的維護 API 使用規則，任何更改都須要通過認真的檢查審覈，並與用戶溝通以防止惹怒用戶。

##SSL

安全是一個關鍵因素。使用 HTTPS，經過加密和驗證，以保證用戶和服務器之間的通訊的完整性，並防止中間人攻擊， 從而提供一個安全的 API 訪問環境。 甚至能夠考慮不提供經過非安全HTTP 的 API訪問。

##操做簡單

當你的 API 有數百到數千用戶的時候，你須要考慮一整套的高級特性支持。

##訪問控制

您須要爲開發人員提供 key 訪問您的API，阻擋黑客入侵。你也會但願限制API用戶的流量，防止用戶的行爲致使API崩潰——不論他是有意或無心的。

##監控

你須要知道你的 API 什麼時候失效，什麼時候必須重啓。你還須要知道你的 API 使用狀況：是誰在什麼時候何地使用 API？。

##集成

您可能須要向用戶提供 API 使用狀況的分析和報告，也可能須要集成一個計費系統，爲 API 使用收費。

其中一些特性是不容易實現的。事實上，實現這些特性多是整個 API 開發週期的更復雜的方面之一。可是萬變不離其宗，再次強調，核心仍是要保持它的簡單。 不要試圖推到重建本身的方案，相反，使用現成的 API 方案來管理您的API。將精力投入到業務相關的部分，從而與你的競爭對手產生差別化。

建立一套成功的API，使得架構和業務更加靈活，甚至將推進業務和收入增加，並激勵創新。 要記得——保持簡單！