03.03.JSON API

JSON APIでモックデータをレスポンスするためのドキュメントです。

project.yaml

project.yamlのajaxを設定すると、モックJSONデータをレスポンスすることができます。

ajax.root

モックJSONデータのルートディレクトリです。プロジェクトルートからの相対パスを指定します。

例

ajax:
  root: ./ajax

project_root/project.yamlの場合、project_root/ajax/がモックJSONデータのルートディレクトリとなります。

ajax.jsonp_callback_name

jsonp_callback_nameでJSONP用のコールバックパラメータ名を設定すると、設定されたパラメータをつけてリクエストされた場合JSONP(application/javascript)のレスポンスを返します。

例

ajax:
  root: ./ajax
  jsonp_callback_name: callback

http://localhost:3183/test?callback=callbackFunc

callbackFunc({"param":"value"})

モックJSONデータファイル

モックJSONデータとして返すデータファイルはJSONとYAML形式に対応しています。どちらを選んでも良いですが、コメントが書けて仕様の共有面で利点があるYAMLを推奨しています。

例

project_root/ajax/api/test.yamlという以下のようなデータファイルを作ります。

project_root/ajax/api/test.yaml

title: test.yaml
hash:
  hashArray:
    -
      id: 1
      name: name1
    -
      id: 2
      name: name2
intArray:
  - 1
  - 2

これをAeromockでレスポンスするには、http://localhost:3183/api/testでリクエストします。データファイルの拡張子を除去したURLでリクエストしてください。

すると以下のようにtest.yamlがJSON形式に変換されてレスポンスされます。

http://localhost:3183/api/test

{
    "title": "test.yaml",
    "hash": {
        "hashArray": [
            {
                "id": 1,
                "name": "name1"
            },
            {
                "id": 2,
                "name": "name2"
            }
        ]
    },
    "intArray": [
        1,
        2
    ]
}

ルート要素が配列

ルート要素が配列となるケースにも対応しています。

project_root/ajax/api/array.yaml

- element1
- element2

http://localhost:3183/api/test/array

[
    "element1",
    "element2"
]

複数パターンデータ

同じURLのAPIに対して、複数パターンのデータを用意することができます。

project_root/ajax/api/test.yamlの違うパターンのデータファイルを、project_root/ajax/api/test__xxx.yamlという形式で作成します。xxx はデータを特定するための一意な識別子であり、任意の値を設定します。ここではtest__2.yamlとしましょう。

project_root/ajax/api/test__2.yaml

title: test__2.yaml
hash:
  hashArray:
    -
      id: 1
      name: name1
    -
      id: 2
      name: name2
intArray:
  - 1
  - 2

このデータをレスポンスするには、http://localhost:3183/api/test?_dataid=2 でリクエストします。

http://localhost:3183/api/test?_dataid=2

{
    "title": "test__2.yaml",
    "hash": {
        "hashArray": [
            {
                "id": 1,
                "name": "name1"
            },
            {
                "id": 2,
                "name": "name2"
            }
        ]
    },
    "intArray": [
        1,
        2
    ]
}

HTTPメソッドでの制御

HTTPメソッドで利用するデータファイルを変えることができます。データファイル名に__HTTPメソッド名をつけるだけです。HTTPメソッドが指定されていない場合はGETになります。以下に例を示します。

リクエストURI	HTTPメソッド	クエリストリング	データファイル
/test	GET	-	test.yaml or test__get.yaml
/test	POST	-	test__post.yaml
/test	PUT	-	test__put.yaml
/test	DELETE	-	test__delete.yaml
/test	GET	_dataid=2	test__2.yaml or test__get__2.yaml
/test	POST	_dataid=2	test__post__2.yaml
/test	PUT	_dataid=2	test__put__2.yaml
/test	DELETE	_dataid=2	test__delete__2.yaml

共通データファイル

モックJSONデータに横断的に組み込みたいようなデータがある場合、共通データファイルとして定義することができます。

プロジェクトルートディレクトリにajax.groovyというスクリプトファイルを用意します。ajax.groovyでは、リクエストの状況に応じてどの共通データファイルを利用するかという制御をすることができます。

例

共通データファイルとして、project_root/ajax/common/common.yamlを用意します。

project_root/ajax/common/common.yaml

commonProp: commonPropValue
commonHash:
  prop1: prop1Value

ajax.groovyでは共通データファイル（拡張子無し）のパスの配列を返すよう実装します。パスはモックJSONデータのルートが起点です。

ajax.groovy

return ["common/common"]

この例では、どのような場合でもproject_root/ajax/common/common.yamlが共通データファイルとして利用されます。共通データファイルが適用されたモックJSONデータは以下のようになります。

http://localhost:3183/api/test

{
    "commonProp": "commonPropValue",
    "commonHash": {
        "prop1": "prop1Value"
    },
    "hash": {
        "hashArray": [
            {
                "id": 1,
                "name": "name1"
            },
            {
                "id": 2,
                "name": "name2"
            }
        ]
    },
    "intArray": [
        1,
        2
    ],
    "title": "test.yaml"
}

複数の共通データファイル

ajax.groovyが返す戻り値は配列となっているので、共通データファイルは複数設定することができます。

project_root/ajax.groovy

return ["common/common", "common/common2"]

データファイルのプロパティの上書き

共通データファイルを利用する場合、プロパティ名の衝突が発生します。この場合は、最後に適用されたデータファイルのプロパティで上書きされます。

データファイルの適用順は、共通データファイルの配列定義順 → 各データファイルとなります。

共通データファイルのプロパティに追記

共通データファイルのプロパティを上書きではなく追記したい場合、追加する方に__additional: trueという特殊なプロパティを設定することで追記が可能です。

例として、project_root/ajax/common/common.yamlのcommonHashにプロパティを追加してみましょう。

project_root/ajax/api/additional.yaml

title: additional.yaml
commonHash:
  __additional: true
  prop2: prop2Value

以下のように、commonHashにprop2がマージされた形式でレスポンスされます。

http://localhost:3183/api/additional

{
    "commonProp": "commonPropValue",
    "commonHash": {
        "prop1": "prop1Value",
        "prop2": "prop2Value"
    },
    "title": "additional.yaml"
}

ビルトイン変数

ajax.groovy内では、Aeromockで定義されているビルトイン変数を参照することができます。ビルトイン変数ではREQUEST_URIやUSER_AGENT等でリクエストの情報を参照できるので、これらの変数を使って適用する共通データを動的に変えるというテクニックが使えます。

カスタムレスポンス

任意のレスポンスコードやレスポンスヘッダ返すことができます。データファイルに__responseという特殊なプロパティを設定します。

例

ステータスコードが400、2つの特殊なヘッダを追加してレスポンスしてみましょう。これを実現するには、データファイルに__responseを定義し、codeとheadersのプロパティを設定します。

project_root/ajax/api/custom_response.yaml

title: custom_response.yaml
__response:
  code: 400
  headers:
    X-Aeromock-Header1: aeromock-header1
    X-Aeromock-Header2: aeromock-header2