KayaMemo

結構昔からあるサービスらしいけれど、
以下の記事を見て、実際に使ってみた。
[Apiary]Markdownで始めるAPI開発とAPIドキュメント作成

アカウント作成

サイトにアクセス。
apiary

Sign Upからアカウント作成。
Githubアカウントか、Twitterでのログインも可能なよう。

アカウントを作成すると、まず一つ作ってみよう、って事で、API名を入力してね、ってでる。
適当に入力してSAVE。
test-apiで作ってみた。
(名前は他のユーザーと被っていても大丈夫。API名は適当に連番を付けて振り分けられ、公開URLも被らないように作成される)

作成すると、見本が出来た状態で開く。
この左のエディタ画面でMarkDown形式でドキュメントを作成していくと、
右側にレンダリング結果が作成され、さらにAPIも自動で生成される。

シンプルなGETのAPIを作ってみる

チュートリアルがあるので、それを見ながら。
API Blueprint Tutorial

以下、完成markdown

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

FORMAT: 1A

#Sample API
サンプルAPI

#Group Sample
Sampleグループ

##Sample [/list]
###Sample Get List [GET]

+ Response 200 (application/json)

        "data":{
            [{
                "id":1
                "name":"taro"
            },{
                "id":2
                "name:"jiro"
            }]
        }

コード詳細

FORMAT: 1A

APIのフォーマットをここで指定できるよう。
無料版だとあまり関係ないかも。正直、理解出来ていません。 おまじないと思って…。

#Sample API

最初の#でこのAPIのタイトル。

#Group Sample

次の#Groupで、グルーピングが可能？

##Sample [/list]

ここでエンドポイントを指定。[]の前には半角スペースをお忘れなく。

###Sample Get List [GET]

エンドポイントの指定のすぐ下で、メソッドの指定。
このメソッドの指定部分が、サンプル実行のボタンとして表示されるよう。

+ Response 200 (application/json)

レスポンスのコードと型を指定して、その下に実際に返却される値を記述。
今回はJSONフォーマットで記述している。
コードを指定出来るということは、エラー時の挙動も記述できると思われる(未確認)。

実行

以下のエンドポイントにアクセスすると、定義したJSONがそのまま返ってくる。
http://private-0b253-test4095.apiary-mock.com/list

右側のレンダリングされた画面でも実際に実行結果をヘッダー付きで見られる。

API部分をクリックすると、詳細が表示され、Call Resourceで実際に叩く事が可能。

結果が、header情報付きで確認出来る。

サンプルコードの出力

右側のエリア右上にある、Swith to Exampleをクリックする。

切り替わった後、デフォルトで、Rawが選択されている箇所のプルダウンから、任意の言語を選択すると、
その言語でのAPIの叩き方のサンプルコードが表示される。
例えばPHPだとこんな感じ。

1
2
3
4
5
6
7
8
9
10
11

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "http://private-0b253-test4095.apiary-mock.com/list");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);

他にも様々な種類の言語のサンプルコードが出力可能。

cURL、Java、JavaScript、Node.js、Perl、Python、PHP、Ruby
Go、C#、Visual Basic、Groovy、Objective-c、Swift、Swift Representor

料金

気になるお値段は、単純な？範囲だと無料。
プライベートな状態での開発をしようとすると有料となるみたい。
(値段表を見てもよくわからなかったが)

Pricing & Plans

次回

次は、POSTの送信を試してみる予定。