2016年3月28日月曜日

API Blueprint の構文

イメージ

API Blueprint は Web API の仕様を記述するためのマークアップ言語です。マークアップの構文は Markdown から拡張されています。

FORMAT: 1A

# NervousKidKitten
神経質な子供の子猫の Web API です。

# Group Greethings
挨拶に関連したすべてのリソースのグループです。

## メッセージ [/message]

### メッセージを取得 [GET]

+ Response 200 (text/plain)

        Hello World!

API Blueprint をサポートする様々なツールを使うことにより、Web API のモック サーバーを立ち上げたり、API ドキュメントの生成などが簡単に行えるようになります。

ここでは、公式のチュートリアルを基にして API Blueprint の構文について簡単に説明します。

メタデータ

API Blueprint はメタデータから始まります。FORMAT は API Blueprint のバージョンを表します。

FORMAT: 1A


API 名

ドキュメント内の最初の見出しは API 名となり、続く文は API の説明となります。

# NervousKidKitten
神経質な子供の子猫の Web API です。


リソース グループ

見出しの記号 (#) の直後に Group キーワードを付けると、その見出しはリソース グループとなります。

# Group Greethings
挨拶に関連したすべてのリソースのグループです。

後述するリソースは、別のリソース グループが定義されるまで、このリソース グループに属します。

リソース

見出しの末尾に角括弧 ([]) で括ったリソースの URI を付けます。

## メッセージ [/message]


アクション

サブヘッダーの末尾に角括弧 ([]) で括った HTTP メソッドのアクション名を付けます。

### メッセージを取得 [GET]

POST などでサーバーにデータを送信する場合は、次のように記述します。

### 新しいメッセージを作成 [POST]
新しいメッセージを作成することができます。このアクションはメッセージを含む JSON オブジェクトを受け取ります。

+ message (string) - メッセージ

+ Request (application/json)

        { "message": "おはよう" }

アクションにはレスポンスが必要です。レスポンスはアクション内のリスト項目として定義します。

### メッセージを取得する [GET]

+ Response 200 (text/plain)

        Hello World!

JSON 形式でレスポンスを返す場合は、次のように記述します。

### メッセージを取得する [GET]

+ Response 200 (application/json)

        { "message": "Hello World!" }

また、DELETE のように返す値がない場合には、ボディー部なしのレスポンスを返すように記述します。

### 削除 [DELETE]

+ Response 204


URI テンプレート

リソースの URI のうち中括弧 ({}) で括った部分が URI テンプレートとなります。

## メッセージ [/messages/{message_id}]


URI パラメーター

URI パラメーターは URI テンプレートの情報を補足します。リスト項目として定義し、名前、型に続けて説明を記述します。

+ Parameters
    + message_id (number) - メッセージの ID


おわりに

ここで挙げた構文は、あくまでもチュートリアルに書かれている内容です。API Blueprint は非常に柔軟な言語であるため、最初の例は、以下のようにもっとシンプルに記述することもできます。

FORMAT: 1A

# NervousKidKitten
神経質な子供の子猫の Web API です。

# GET /message
+ Response 200 (text/plain)

        Hello World!

API Blueprint の完全な構文 (言語仕様) については API Blueprint Specification を参照してください。

リンク

0 件のコメント:

コメントを投稿