白宮Web API的指南和示例

• 設計HTTP介面和RESTful Web服務
• API Facade Pattern，作者：Brian Mulloy，Apigee
• Web API設計，作者：Brian Mulloy，Apigee
• 菲爾丁關於REST的論文

• 將API的版本號放在URL中（參見下面的示例）。不接受任何未指定版本號的請求。
• 允許使用者像這樣請求JSON或XML等格式：
  
  • http://example.gov/api/v1/magazines.json
  • http://example.gov/api/v1/magazines.xml

• URL標識資源。
• 網址應包含名詞，而不是動詞。
• 使用複數名詞只是為了一致性（沒有單數名詞）。
• 使用HTTP謂詞（GET，POST，PUT，DELETE）對集合和元素進行操作。
• 不應該比資源/識別符號/資源更深巢狀了。
• 將版本號放在URL的尾部，例如http://example.com/v1/path/to/resource。
• URL 和Header的選擇：
  
  • 如果更改了你編寫的邏輯以處理響應，請將其放入URL中。
  • 如果它沒有更改每個響應的邏輯，例如OAuth資訊，請將其放在標題Header中。
• 在逗號分隔列表中指定可選欄位。
• 格式應採用api/v2/resource/{id} .json的形式

• 雜誌資源列表：
  
  • GET http://www.example.gov/api/v1/magazines.json
• 過濾是一種查詢：
  
  • GET http://www.example.gov/api/v1/magazines.json?year=2011&sort=desc
  • GET http://www.example.gov/api/v1/magazines.json?topic=economy&year=2011
• JSON格式的一個雜誌資源：
  
  • GET http://www.example.gov/api/v1/magazines/1234.json
• 本雜誌中的所有文章（或屬於本雜誌）：
  
  • GET http://www.example.gov/api/v1/magazines/1234/articles.json
• 本雜誌中的所有文章都是XML格式：
  
  • GET http://example.gov/api/v1/magazines/1234/articles.xml
• 在逗號分隔列表中指定可選欄位：
  
  • GET http://www.example.gov/api/v1/magazines/1234.json?fields=title,subtitle,date
• 在特定雜誌中新增新文章：
  
  • POST http://example.gov/api/v1/magazines/1234/articles

• 非複數名詞：
  
  • http://www.example.gov/magazine
  • http://www.example.gov/magazine/1234
  • http://www.example.gov/publisher/magazine/1234
• 網址中的動詞：
  
  • http://www.example.gov/magazine/1234/create
• 在查詢字串之外過濾
  
  • http://www.example.gov/magazines/2011/desc

HTTP動詞

應使用HTTP謂詞或方法，以符合HTTP / 1.1標準下的定義。動作時與正在處理的媒體型別及其當前狀態有關。以下是HTTP謂詞如何對映到特定上下文中的建立，讀取，更新，刪除操作的示例：
/dogs
POST: 建立一個狗
GET: 列表
UPDATE:更新
DELETE:刪除所有

響應

• key中不能有值
• 不能有內部特定的名稱（例如“node”和“taxonomy term分類術語”）
• 後設資料應僅包含響應集的直接屬性，而不包含響應整合員的屬性

"tags": [
  {"id": "125", "name": "Environment"},
  {"id": "834", "name": "Water Quality"}
],

"tags": [
  {"125": "Environment"},
  {"834": "Water Quality"}
],

錯誤處理

錯誤響應應包括常見的：HTTP狀態程式碼，開發人員的訊息，終端使用者的訊息（適當時），內部錯誤程式碼（對應於某些特定的內部確定的ID），開發人員可以找到更多資訊的連結。
例如：

{
  "status" : 400,
  "developerMessage" : "Verbose, plain language description of the problem. Provide developers
   suggestions about how to solve their problems here",
  "userMessage" : "This is a message that can be passed along to end-users, if needed.",
  "errorCode" : "444444",
  "moreInfo" : "http://www.example.gov/developer/path/to/help/for/444444,
   http://drupal.org/node/444444",
}

版本

• 永遠不要在沒有版本號的情況下發布API。
• 版本應為整數，而不是十進位制數，字首為“v”。例如：
  
  • 好：v1，v2，v3
  • 差：v-1.1，v1.2,1.3
• 維護至少一個版本的API。

記錄限制

• 如果未指定限制，則返回預設限制。
• 要獲得記錄51到75，請執行以下操作：
  
  • http://example.gov/magazines?limit=25&offset=50
  • offset = 50表示'跳過前50條記錄'
  • limit = 25表示'最多返回25條記錄'

{
    "metadata": {
        "resultset": {
            "count": 227,
            "offset": 25,
            "limit": 25
        }
    },
    "results":
}

請求和響應示例
API資源

• GET /magazines
• GET /magazines/[id]
• POST /magazines/[id]/articles
•  

{
    "metadata": {
        "resultset": {
            "count": 123,
            "offset": 0,
            "limit": 10
        }
    },
    "results": [
        {
            "id": "1234",
            "type": "magazine",
            "title": "Public Water Systems",
            "tags": [
                {"id": "125", "name": "Environment"},
                {"id": "834", "name": "Water Quality"}
            ],
            "created": "1231621302"
        },
        {
            "id": 2351,
            "type": "magazine",
            "title": "Public Schools",
            "tags": [
                {"id": "125", "name": "Elementary"},
                {"id": "834", "name": "Charter Schools"}
            ],
            "created": "126251302"
        }
        {
            "id": 2351,
            "type": "magazine",
            "title": "Public Schools",
            "tags": [
                {"id": "125", "name": "Pre-school"},
            ],
            "created": "126251302"
        }
    ]
}

{
    "id": "1234",
    "type": "magazine",
    "title": "Public Water Systems",
    "tags": [
        {"id": "125", "name": "Environment"},
        {"id": "834", "name": "Water Quality"}
    ],
    "created": "1231621302"
}

[
    {
        "title": "Raising Revenue",
        "author_first_name": "Jane",
        "author_last_name": "Smith",
        "author_email": "jane.smith@example.gov",
        "year": "2012",
        "month": "August",
        "day": "18",
        "text": "xxxxxxx.. "
    }
]

模擬響應

建議每個資源在測試伺服器上接受'mock'引數。傳遞此引數應返回模擬資料響應（繞過後端）

。在開發早期實現此功能可確保API表現出一致的行為，支援測試驅動的開發方法。注意：如果mock引數包含在對生產環境的請求中，則應引發錯誤。

JSONP
解釋JSONP最簡單是用一個例子。這是StackOverflow中的定義：

假設您在域名abc.com上，並且您想向域xyz.com發出請求。要做到這一點，你需要跨越域邊界，在大多數瀏覽器領域都是禁忌。繞過此限制的一個專案是標籤。

當您使用這個指令碼標籤時，跨域限制將被忽略，但在正常情況下，您無法對結果做任何事情，只會對指令碼進行評估。

當你向啟用了JSONP的伺服器發出請求時，你會傳遞一個特殊引數，告訴伺服器一些關於您的頁面的資訊。這樣，伺服器就能夠以您的頁面可以處理的方式很好地包裝其響應。例如，假設伺服器需要一個名為“callback”的引數來啟用其JSONP功能。然後你的請求看起來像：
http://www.xyz.com/sample.aspx?callback=mycallback

如果沒有JSONP，這可能會返回一些基本的javascript物件，如下所示：
{ foo: 'bar' }

但是，使用JSONP時，當伺服器收到“callback”引數時，它會以不同的方式包裝結果，返回如下內容：
mycallback({ foo: 'bar' });

如您所見，它現在將呼叫您指定的方法。因此，在您的頁面中，您定義了回撥函式：
mycallback = function(data){ alert(data.foo); };