本文中的建議適用於任何API。但是，當應用程式使用動態語言（如JavaScript）編寫而不是更靜態的語言（如Java）時，我們會考慮更容易遇到的一些問題。

Node.js有時被稱為膠水，它將系統導向的體系結構保持在一起，因為它易於與多個後端服務通訊並將結果拼接在一起。出於這些原因，我們將看到的示例將使用Node.js風格的JavaScript編寫。

對資料很吝嗇

當遇到要在API響應中使用的物件時，很容易傳遞物件的每個屬性。實際上，通常更容易傳送未經修改的整個物件，而不是整個物件的屬性進行一些新增或刪除。

想想您從社交媒體平臺獲得使用者的情況。也許在您的應用程式中，該物件類似於以下內容：

{
  "id": 10,
  "name": "Thomas Hunter II",
  "username": "tlhunter",
  "friend_count": 1337,
  "avatar": "https://example.org/tlhunter.jpg",
  "updated": "2018-12-24T21:13:22.933Z",
  "hometown": "Ann Arbor, MI"
}

假設是您自己正在構建API，並且您已經被特別要求提供使用者的識別符號，使用者名稱，人類可讀的名稱以及他們的頭像。但是，將完整物件提供給API的使用者非常簡單，因為可以簡單地執行以下操作：

res.send(user);

但是，按照需求和要求卻應該傳送如下使用者屬性：

res.send({
  id: user.id,
  name: user.name,
  username: user.username,
  avatar: user.avatar
});

應始終關注業務需求並確定可滿足這些要求的絕對最小資料量。API的消費者真正需要什麼？

這是程式設計中的一個重要概念，它甚至有一個名字：你不需要它（YAGNI）。總是對你傳送的資料感到吝嗇。可以通過使用定義良好的物件表示資料來實現此問題的解決方案以及其他問題。

將上游資料表示為明確定義的領物件

通過將資料表示為明確定義的業務物件，當我們從上游服務請求資料並將其轉換為物件時，我們現在已經建立了一個POJO（Plain Old JavaScript Object）。這樣的物件既方便又有風險。

相反，讓我們將這些物件表示為DO（領域物件）。這些領域物件將要求我們將一些規則應用於我們從上游檢索過來的資料，它們還可檢查存在的屬性是否屬於正確型別。

使用向前相容的屬性命名

在API響應中命名物件的屬性時，請確保以這樣的方式命名它們，使它們與將來計劃進行的任何更新都向前相容。

規範化概念和屬性

使用積極的，“快樂”的名字

負面的示例如disable_notification，應該使用正面enable_notification，原因是作為開發人員很容易被雙重否定所迷惑：如unavailable: false， 而正面available: true很容易理解。

這裡有一些負面詞語儘量避免：broken, taken, secret, debt，它們相應正面詞語是： functional, free, public, credit

public是積極的，private是負面的。

應用魯棒性原則

確保遵循可靠性原則，無論它適用於您的API。引自維基百科，這個原則是：

保守你的所作所為，要接受別人的自由。（嚴以律己 寬以待人）

這個原則最明顯的應用是關於HTTP頭。根據HTTP RFC，標題應該包含單詞的第一個字母的大寫字元，並用連字元分隔。但是，在技術上可以是任何大寫字母並且技術上仍然可以接受，例如。Content-Typecontent-TYPE

魯棒性原則的前半部分是保守的。這意味著您應始終使用首選標頭大小寫響應客戶端。您無法確切地知道您的API的使用者能夠正確讀取格式良好且格式化的標題。並且API應該可以被儘可能多的不同消費者使用。

這個原則的後半部分是你從別人那裡接受的自由。這意味著，對於HTTP標頭，您應該將每個傳入標頭規範化為一致的格式，以便您可以讀取預期值而不管大小寫。

測試所有錯誤條件

如果可能，建立接受測試，呼叫各種錯誤並測試響應。

退後一步

在企業環境中，很容易進入允許複雜客戶端庫處理與服務的所有通訊的模式。同樣，很容易允許複雜的服務庫將物件的所有序列化處理成客戶端可消費的格式。有了這麼多的抽象，公司可能會達到這樣的程度，即沒有人知道通過線路傳送的資料是什麼樣的。

當這些情況發生時，通過網路傳輸的資料量可能會失控。轉移個人身份資訊（PII）的風險也會增加。並且，如果您的API需要被外部世界消費，這可能會導致大量痛苦的重構以進行清理。

時不時地“退後一步”很重要。停止使用組織事實上的工具來檢視API。相反，使用通用的現成產品來檢視API。使用HTTP API時，實現此目的的一個此類產品是Postman。此工具對於檢視原始HTTP有效負載非常有用。它甚至還有一個方便的介面來生成請求和解析響應。