API BlueprintとaglioでAPIの仕様書を作成しました

API Blueprintとは

API BlueprintとはWeb APIのドキュメントを書くための記法です。
以下の書籍で知り、仕様書を作成してみました。

Web API The Good Partsまとめ
Web APIに特化した書籍を購入したので、気になった箇所を簡単にまとめます。 Web APIとは何か サーバー側の情報を書き換えたり、サーバー側に置かれた情報を取得できたりするウェブシステムで、プログラムからあくせすし...

株価を返すAPIドキュメント例

FORMAT: 1A
 
# Group 株価
 
## 株価情報取得 [/v1/datasets/{code}{?start-date,end-date,frequency}]
 
### 株価情報取得API [GET]
 
#### 処理概要
 
* 指定した株価情報を返す。
* start-dateとend-dateを指定した場合は、その期間の株価情報を返す。
* frequencyで日足、週足、月足、四半期足、年足の株価を返す。
 
+ Parameters
 
    + `code`: 3798 (number, required) - 銘柄番号
    + `start-date`: `2018-08-01` (string, optional) - 取得開始日
    + `end-date`: `2018-08-31` (string, optional) - 取得終了日
    + frequency: `none` (enum, optional) - 取得間隔
        + `none` (string)
        + `daily` (string)
        + `weekly` (string)
        + `monthly` (string)
        + `quarterly` (string)
        + `annual` (string)

+ Response 200 (application/json)
 
    + Attributes
        + dataset (required)
            + code: 3798 (number, required)
            + name: ULSグループ (string, required)
            + startDate: `2018-08-01` (string)
            + endDate: `2018-08-31` (string)
            + frequency: `daily` (string)
            + data (array)
                + (object)
                    + date: `2018-08-01` (string, required)
                    + asset: 100 (number) - 発行済株式総数
                    + profit : 100 (number) - 当期純利益
                    + open: 100 (number) - 始値
                    + high: 100 (number) - 高値
                    + low: 100 (number) - 安値
                    + close: 100 (number) - 終値
                    + volume: 100 (number) - 出来高
                + (object)
                    + date: `2018-08-02` (string, required)
                    + asset: 100 (number) - 発行済株式総数
                    + profit : 100 (number) - 当期純利益
                    + open: 100 (number) - 始値
                    + high: 100 (number) - 高値
                    + low: 100 (number) - 安値
                    + close: 100 (number) - 終値
                    + volume: 100 (number) - 出来高

+ Response 404 (application/json)
 
    + Attributes
        + error (required)
            + code: 404 (number, required)
            + message: ULSグループ (string, required) - 株価が見つかりません。

複数ドキュメントをまとめる

複数ドキュメントをまとめるにはhtmlコメントアウトしたincludeを使用します。

FORMAT: 1A

<!-- include(stocks.md) -->

<!-- include(performances.md) -->

<!-- include(datasets.md) -->

参考サイト

以下のサイトが非常にわかりやすくまとまっています。

【API Blueprintの使い方】Web APIの仕様書を書く・読む・実行する | DevelopersIO
Developers.IOは、AWS、iOS/Androidアプリ、ビッグデータ、Alexa等の最新技術情報からリモートワークや働き方に関する記事まで多彩なトピックを紹介するクラスメソッドのオウンドメディアです。

さいごに

今回はパラメーターの選定にQuandlを参考にしました。

APIの設計に重要なのは、「覚えやすく、どんな機能を持つURIなのかがひと目でわかる」です。
既存のわかりやすいドキュメントを参考に、わかりやすいAPIの作成を心がけていきます。

コメント