RAML (RESTful API Modeling Language) 是ㄧ以YAML為基礎、專門用來描述 RESTful API、且人與機器都看得懂的標記語言。
因為透過RAML去描述的API,機器也能夠看得懂,所以可以衍生出一些附加的功能服務,像是解析並自動產生對應的 API Console、API Client、API Server、API User Document…等。
Root Section
RAML文檔最開始是Root Section,是用來做 API 基本的描述用,像是 API 的標題、API 版本、API 基底位置、相關文檔、與 schema 及其參考…等。
就像下面這樣:
#%RAML 0.8
---
title: GitHub API
baseUri: http://api.github.com/{version}
version: v1
一開始要描述RAML的版本,接著就是帶入 API 的標題等。以這例子來說,這邊是在描述 GitHub 的 API ,API 的基底位置是 http://api.github.com/{version}
,基底位置內寫的 {version} 會被實際的版本取代,而目前的版本是 v1 。
除了上面範例提到的設定外,還有其它可用的設定,這邊不深究,請直接參閱下表整理:
Property | Required | Description |
title | Yes | API 文件標題 |
version | No | API 版本 |
baseUri | No | API 基底位置 |
baseUriParameters | No | API 基底位置的參數 |
Protocols | No | API 支援的通訊協定 |
mediaType | No | API 預設的MediaType |
schemas | No | schema |
uriParameters | No | API 相關參數 |
documentation | No | API 相關文件 |
Resource
Root Section設定好我們已經有 API 的基底位置了,所有的 API 都是以這基底下去延伸,我們可能為了讓 API 更為清楚,而在 API 基底位置下再加上幾層 Resource 進去,像是 GitHub API 的 API 基底位置是 https://api.github.com/
,Gist 相關的功能就被放在 /gists
Resource 下, 所以對應的 API 位置就變成 https://api.github.com/gists/
這樣。
所以 Resource 在 RAML 這邊的設定就是以 /
開頭,像是下面這樣:
/gists:
要做巢狀的 Resource 也是可以的:
/gists:
/{gistId}:
Methods
Resource 定義完,我們可以決定 Resource 對應下列哪些Method:
- get
- put
- post
- delete
像是 GitHub 的 Gist API 支援get,所以我們可以像下面這樣定義:
/gists:
/{gistId}:
get:
Query parameters
Resource 跟 Method 都設定好,有的簡單的 API 到這邊就可以動了,但是有的比較複雜的會要帶 QueryString 當參數,這時我們就需要在對應的 Method 後設定 queryParameters ,像是下面這樣:
/gw:
get:
queryParameters:
method:
type: string
enum: ["album.channel.get"]
default: "album.channel.get"
channel:
type: string
enum: ["z"]
appKey:
type: string
default: "myKey"
format:
type: string
enum: ["xml", "json"]
pageNo:
type: integer
pageSize:
type: integer
queryParameters 後面帶上 QueryString 內所含的參數設定,每個參數設定都可套用需要的 Named Parameters,Named Parameters 這邊可參考下表:
displayName | Required | 顯示名稱 |
title | Yes | 標題 |
type | No | 型態 |
enum | No | 列舉值 |
pattern | No | |
minLength | No | 最小長度 |
maxLength | No | 最大長度 |
minimum | No | 最小值 |
maximum | No | 最大值 |
example | No | 範例 |
repeat | No | |
required | No | 必要值 |
default | No | 預設值 |
Response
Response 這塊是定義 API 的回傳值,一樣是接在 Method 後面,帶上 responses 設定,後面接著 HTTP Status Code ,接著是 body、對應的MediaType、以及example,像是下面這樣:
/gists:
/{gistId}:
get:
responses:
404:
body:
application/json:
example: |
{
"message": "Not Found",
"documentation_url": "http://developer.github.com/v3"
}
Conclusion
RAML 的文檔基礎來說就是這樣而已,當然還有些細部的設定參數這邊沒有介紹到,若有需要請自行查閱 Spec 文檔。
最後這邊要提一下,一開始筆者就有提到了 RAML 文檔機器也能看得懂,因此有延伸出來很多服務。
比較重要的像是 API Designer 就能輔助我們編輯 RAML 文檔
編輯的同時右側這邊會即時呈現對應的 API Console
藉由比對我們可以更清楚了解 RAML 文檔的欄位會用在哪邊,也可以即時叫用 API。
另外就是 API Console,是跟 API Designer 右側一樣的東西,可解析 RAML 檔產生對應的互動式文檔。
這些 Tool 都有開源在 GitHub 上,有需要都可以自行架設。