API Blueprint 撰寫教學

API Blueprint 是一個 API 文件撰寫風範,而且也有相關的工具可以將寫好的文件轉換成網頁,其實 API Blueprint 的寫法十分地簡單,先讓我們從開頭開始。

中繼資料

FORMAT: 1A  

所謂的中繼資料即是 鍵名:值,從上述範例中你可以看到我們將 FORMAT 賦予一個 1A 的值,FORMAT 關鍵字是用來表示這份 API Blueprint 的版本

API 名稱 & 註釋

# 投票

投票 API 能夠讓客戶檢視投票統計並參與投票。

# 符號當作開頭的就會被定義成標題。而藍圖中的第一個標題會是你 API 文件的名稱,在這個範例中 投票 即是我們 API 文件的名稱。

順帶一提,你可以用 # 的數量表示標題的階級,在稍後就可以看見詳細的說明。而伴隨在標題之後那一行是註釋

資源群組

現在是時候替你的 API 資源開始撰寫文件了。在開頭使用 Group 關鍵字可以讓你建立資源群組,你可以把「資源群組」當作是一個分類來看待。

# Group 提問

API 中與「提問」有關的資源。  

資源

我們在上述的範例中建立了一個「提問資源群組」,現在我們希望在這個群組中建立一個資源就可以像下面這樣:

## 提問總匯 [/questions]

注意:這個標題的後面會用方括號包住一個 URI,用以敘述如何和這個資源互動。

動作

API Blueprint 允許你在資源上指派動作。在資源內的子標題即會被定義為動作,且動作後面需帶有一個 HTTP 方法

### 列出所有提問 [GET]

動作需要帶有至少一個回應。「一個帶有數個項目並擺至於動作內的清單」就是回應的定義。清單內的項目可以用 +, * 或是 - 作為前輟符號

舉例來說,下面會回傳一個狀態碼為 200 並帶有 JSON 資料格式的回應。

+ Response 200 (application/json)

        [
            {
                "question": "最喜歡的程式語言?",
                "published_at": "2014-11-11T08:40:51.620Z",
                "url": "/questions/1",
                "choices": [
                    {
                        "choice": "Swift",
                        "url": "/questions/1/choices/1",
                        "votes": 2048
                    }, {
                        "choice": "Python",
                        "url": "/questions/1/choices/2",
                        "votes": 1024
                    }, {
                        "choice": "Objective-C",
                        "url": "/questions/1/choices/3",
                        "votes": 512
                    }, {
                        "choice": "Ruby",
                        "url": "/questions/1/choices/4",
                        "votes": 256
                    }
                ]
            }
        ]

注意:當你在狀態碼後指定了內容種類就會自動產生 Content-Type HTTP 標頭。所以你不需要額外再去手動指定 Content-Type 標頭。

現在讓我們建立另一個「動作」,這動作用來建立新的提問,像下面這樣你就可以建立一個帶有註釋、資料結構的動作。

### 建立一個新提問 [POST]

當你想要建立新的提問就可以運用這個動作。這個動作需要傳入一個帶有提問還有答案合集的 JSON 物件。

+ question (string) - 提問名稱
+ choices (array[string]) - 答案陣列合集。

為此,我們替這個動作建立一個 JSON 資料格式的請求:

+ Request (application/json)

            {
                "question": "最喜歡的程式語言?",
                "choices": [
                    "Swift",
                    "Python",
                    "Objective-C",
                    "Ruby"
                ]
            }

然後在這一個動作將會回傳一個帶有標頭、內容且狀態碼是 201 的回應。

+ Response 201 (application/json)

    + Headers

            Location: /questions/1

    + Body

                {
                    "question": "你最喜歡的程式語言?",
                    "published_at": "2014-11-11T08:40:51.620Z",
                    "url": "/questions/1",
                    "choices": [
                        {
                            "choice": "Swift",
                            "url": "/questions/1/choices/1",
                            "votes": 0
                        }, {
                            "choice": "Python",
                            "url": "/questions/1/choices/2",
                            "votes": 0
                        }, {
                            "choice": "Objective-C",
                            "url": "/questions/1/choices/3",
                            "votes": 0
                        }, {
                            "choice": "Ruby",
                            "url": "/questions/1/choices/4",
                            "votes": 0
                        }
                    ]
                }

URI 模板

現在建立新的資源,我們先稱其為 提問,我們希望這個「提問」資源會回傳單個提問。

## 提問 [/questions/{question_id}]

提問 資源的 URI 運用到了變數,這也被稱為 URI 模板。在這個範例中,有個叫做 question_id 的編號變數,在 API Blueprint 的 URI 上我們會以 {question_id} 作為撰寫格式。

URI 參數

URI 的參數會被定義在 Parameters 清單中:

+ Parameters
    + question_id (number) - 提問的編號。

question_id 這個參數被定義成 number 資料型態,隨後的是這個參數的註釋。

參閱 API Blueprint 的 URI 參數區段 可以看見更多範例。

動作

現在讓我們替這個資源新增一個「取得提問詳細資料」的動作。

### 檢視提問詳細資料 [GET]

+ Response 200 (application/json)

            {
                "question": "你最喜歡的程式語言?",
                "published_at": "2014-11-11T08:40:51.620Z",
                "url": "/questions/1",
                "choices": [
                    {
                        "choice": "Swift",
                        "url": "/questions/1/choices/1",
                        "votes": 2048
                    }, {
                        "choice": "Python",
                        "url": "/questions/1/choices/2",
                        "votes": 1024
                    }, {
                        "choice": "Objective-C",
                        "url": "/questions/1/choices/3",
                        "votes": 512
                    }, {
                        "choice": "Ruby",
                        "url": "/questions/1/choices/4",
                        "votes": 256
                    }
                ]
            }

沒有 Body 的回應

同時,我們也希望這個資源也有著一個「刪除」動作。這個動作送出之後,伺服器會回傳一個 204 回應而且不帶有任何內容,這個時候可以像下面這樣做:

### 刪除 [DELETE]

+ 回應 204

完整的藍圖

這個完整的 API 藍圖可以在 API Blueprint 範例 中的 投票 API Blueprint 找到。你甚至可以在 http://polls.apiblueprint.org/實際操作上述的 API 方法。當然,你也能夠稍微享受一下文件在 Apiary 渲染的過程

注意:你可以稍微看一下 API Blueprint 專業術語 來協助你更加地了解這些文件。

API Blueprint 工具

拜訪 apiblueprint.org 網站中的工具區段你就能夠找到許多實用的 API Blueprints 工具。


原文來源:API Blueprint Tutorial