【翻譯】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 可以得到和上面一樣的結果。【譯者註：這個需要登陸之後才能有結果，所以，實驗結果根據登陸狀態和使用者識別碼 的不同而不同】

事實上，我通過自己在使用 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，使得架構和業務更加靈活，甚至將推動業務和收入增長，並激勵創新。
要記得——保持簡單！

【翻譯】Win with APIs by keeping it simple