WebAPIドキュメント作成サービス「Apiary」を使ってWebアプリ開発を高速化しよう

いなば

2015.02.16

はじめまして。去年の9月にLIGにジョインしましたフロントエンドエンジニアの稲葉です。最近のマイブームは日本酒です。（お酒は弱いです）

去年の11月くらいからずっとAngularJSにどっぷり浸かっていますが、BackboneJSの方が好きです。
今回は、APIのモックサーバを提供するサービス「Apiary」をご紹介したいと思います。実際の案件でRESTfulなアプリケーションを開発する際、とても便利でした！

Apiaryとは

http://apiary.io/

「API Blueprint」と呼ばれるMarkdownを拡張した言語で、APIのインターフェース仕様書を記述すると、その記述をもとにドキュメントの生成とAPIのモックサーバを同時に用意をしてくれるWebサービスです。

モックサーバを準備する

まずはとにかく実際に使ってみましょう！

IDとPasswordを登録してアカウントを作らなくても、TwitterかGithubアカウントがあればログインができます。
Githubアカウントでログインするとドキュメントの修正履歴をgit管理することが可能になるので、Githubアカウントでログインすることをオススメします。

ログインするとこんな画面が表示されていると思います。

画面左側がエディター画面となっていて、ここにAPI BlueprintでAPIドキュメントを記述していきます。右側はプレビューが表示されます。（プレビュー画面の生成が重たいみたいで、表示されるまでラグがあります）

APIを叩いてみる

ドキュメントの記述方法は後述するので、まずはAPIを実際に叩いてみましょう。
Apiaryでは実際にAPIにアクセスするためのサンプルコードも自動生成してくれます。試しにJavaScriptのサンプルコードを表示してみましょう。

コピーしたサンプルコードをコンソールで実行するとモックサーバから返ってきた内容がalertで表示されるはずです。ログインと同時にjsonを返してくれるモックサーバが用意できてしまいました。

モデルが取得するリソースにこのURLを一旦指定しておげば、サーバーサイドの実装を待たずに開発を進めることができます。

実際にコピーしたサンプルコード

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://private-f232e-book4.apiary-mock.com/notes");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send(null);

ドキュメントを書いてみる

今回作ったApiaryのドキュメントはこちら。
実際にエディタでドキュメントを編集してAPIサーバーを作ってみましょう。

グループをつくる

まずはMarkdownでいうところの「h1」である「#」+「Group」で1つのAPIをグルーピングすることができます。（グレーの枠に囲まれます）

# Group Member

エンドポイントをつくる

次に、グループに属するエンドポイントを記述します。
Markdownでいうところの「h2」でエンドポイントのURLを指定し、「h3」で対応するHTTPメソッド毎にレスポンスを記述していきます。

# Group Member
## Members Collection [/members]
### List all Members [GET]
+ Response 200 (application/json)

        {
            "total": 3,
            "list": [
                {
                    "id": 1,
                    "name": "せいと",
                    "job": "フロントエンドエンジニア"
                    "image": "https://liginc.co.jp/wp-content/uploads/2014/10/daiki_avatar_1413085231-210x210.jpg"
                },
                {
                    "id": 2,
                    "name": "のびすけ",
                    "job": "バックエンドエンジニア",
                    "image": "https://liginc.co.jp/wp-content/uploads/2014/10/daiki_avatar_1413085231-210x210.jpg"
                },
                {
                    "id": 3,
                    "name": "おじいちゃん",
                    "job": "フロントエンドエンジニア"
                    "image": "https://liginc.co.jp/wp-content/uploads/2014/10/daiki_avatar_1413085231-210x210.jpg"
                }
            ]
        }

これでLIGの若手エンジニアの一覧を返すAPIができました。

クエリパラメータを受け取る場合

今度は、1人分の情報を取得するエンドポイントを作ります。
getパラメータで受け取りたい場合、Apiaryでは下記のように波括弧でパラメータ名を囲みます。複数のパラメータを受け取る場合は波括弧の中でカンマで区切って繋げて記述します。

パラメータ名の後の括弧の中には型とサンプルの値、「…」の後にパラメータの説明文を記述します。optionalを指定しなければ必須パラメータとして扱われます。

例：getパラメータでidが必須の場合

## Member [/members/{id}]

+ Parameters
    + id ( number, `1`) ... メンバーのID、型は数値

### Retrieve a Note [GET]
+ Response 200 (application/json)

        {
            "id": 3,
            "name": "おじいちゃん",
            "job": "フロントエンドエンジニア"
            "image": "https://liginc.co.jp/wp-content/uploads/2014/10/daiki_avatar_1413085231-210x210.jpg"
        }

例：パラメータを複数受け取る場合
エンドポイントで受け取るパラメータと対になるようにParametersも記述します。メンバーがたくさん増えたら絞り込み機能もきっと欲しくなるでしょう。

## Members Collection [/members{?q,limit,page,order,order_by}]

+ Parameters
    + q (optional, `おじいちゃん`) ... 検索キーワード
    + limit (number, `10`) ... 表示件数
    + page (number, `1`) ... ページ数
    + order (number, `0`) ... 昇順/降順
    + order_by (string, `updated_at`) ... 並び替え条件

Apiaryの残念なところ

使用していたときはベータ版だったのですが、以下のようなところがありました。

jsonのシンタックスは検知してくれない（API叩いたらjsonパースエラー出てるときはだいだいこれ）
ブラウザから保存する際、競合を全く見ない（これは最初気づかなくて知らぬ間に巻き戻っていてハマりました・・・）

今後の改善を期待したいところです。

その他

今回は紹介だけにとどめますが、他にもSettingsから便利な機能が設定ができたりします。その中でも目ぼしいものは以下に抜粋してみました。

CORS対応（オンにすると全てのモックのリソースにCross-Origin Request Headersを付与してくれる）
Proxy設定（プロキシをかませてリクエストを本番へ向けることができる）
Github連携（ドキュメントの履歴をGit管理できるといろいろと捗ります）

Proxy設定はソースコードをそのままに、実際のAPIにリクエストを投げることができるのでとても便利です。

まとめ

いかがでしたでしょうか。
サーバーサイドの実装を待たずに、クライアントサイドの開発が先行できるので開発スピードの短縮につながりとても良かったです。案件で使用していた際も、ドキュメントがモックになっているのでサーバーサイドのエンジニアとの認識のずれも少なかったです。
実装が完了したタイミングでAPIの向き先を切り替えた際の連結テストも、比較的にスムーズに行うことができました。
開発初期や新規実装の際には、非常に重宝するWebサービスだと思います。

気になる方はぜひ使ってみてください。

それでは、また。

【Webアプリを開発したい方は！】

※ Web制作者でもネイティブアプリが作れる！node-webkitを使ってみよう

※ チャットツールをGitとNode.jsとHerokuでDIYする方法〜環境構築編〜

※ Web開発者に革命をもたらす！「Web Components」超入門

※ Webアプリケーション監視・セキュリティ対策用のオープンソースソフトウェア6選

※ レスポンシブデザインを制作するなら頭に入れておくべき基本事項7つ

LIGはWebサイト制作を支援しています。ご興味のある方は事業ぺージをぜひご覧ください。

Webサイト制作の実績・料金を見る