EN.03.03.JSON API

Document to respond mock json data as JSON API.

project.yaml

When configure ajax section at project.yaml, be able to respond to mock json data.

ajax.root

Root directory of JSON API. Specify a relative path from project root path.

Example

ajax:
  root: ./ajax

ajax.jsonp_callback_name

When configure callback parameter name for JSONP at jsonp_callback_name, request with callback parameter, then respond JSONP(application/javascript) response.

Example

ajax:
  root: ./ajax
  jsonp_callback_name: callback

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

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

If specified path of project.yaml is project_root/project.yaml, project_root/ajax/ is JSON API root directory.

Mock JSON data file

Aeromock supports JSON and YAML format file as data file respond mock json data. May be either, we recommend YAML format, because easy to share some specifications.

Example

Create project_root/ajax/api/test.yaml as follows.

project_root/ajax/api/test.yaml

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

To responde this file, send request to http://localhost:3183/api/test . Without the extension of data file. Then Aeromock respond JSON response with converting to JSON format.

http://localhost:3183/api/test

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

Array root element

Aeromock supports array root element.

project_root/ajax/api/array.yaml

- element1
- element2

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

[
    "element1",
    "element2"
]

Various patterns per API

Aeromock supports various pattern data per API.

Create Different pattern of project_root/ajax/api/test.yaml as project_root/ajax/api/test__xxx.yaml format. xxx is unique id to identify the data. test__2.yaml in this example.

project_root/ajax/api/test__2.yaml

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

To respond this data, send request to 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
    ]
}

Handling HTTP Method

Enable to handle HTTP Method by data file name. It's only name with __(httpmethodname) data file name. If http method has not specified, default method is GET. For example, as the following.

Request URI	HTTP method	Query String	Data file name
/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

Common data file

If you have data you want to include in all or majority, be able to define as common data file.

Create ajax.groovy at project root directory. ajax.groovy is script control to choise common data file depending on the situation of HTTP request.

Example

Create project_root/ajax/common/common.yaml as a common data file.

project_root/ajax/common/common.yaml

commonProp: commonPropValue
commonHash:
  prop1: prop1Value

Implement to return array of common data file of path (without extension). This path is relative path from JSON API.

ajax.groovy

return ["common/common"]

In this example, it is used project_root/ajax/common/common.yaml always as common data file. Mock json data Merged common data as follows.

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"
}

Multiple common data files

ajax.groovy should return array type, so be able to specify multiple common data files.

project_root/ajax.groovy

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

Overwrite property of data file

When uses common data file, property name may be conflict. In this case, the properties of the data file that was last

The order applied data files is array of common data file -> Target data file.

Add data to property of common data file

If you want to add data on property of common data file but to overwrite, possible to specify __additional: true.

For example, add property to commonHash.

project_root/ajax/api/additional.yaml

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

Respond merged prop2 to `commonHash as follows.

http://localhost:3183/api/additional

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

Builtin Variables

In ajax.groovy, be able to refer to builtin variables defined on Aeromock. Request information like REQUEST_URI and USER_AGENT has been prepared, so there are technique to change applying common data dynamically.

Custom Response

Respond specific response code and customized response headers. Specify property named __response on target data file.

Example

Respond 400 status code, two headers. Define __response on the data file, code and headers property in this.

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