Responses

By default, the JSON data is provided directly as root object. Please see this example code of a menu root object.

{
    "headline": "My Menu",
    "menu": [{
            "label": "My Menu Item"
        }]
}

This data structure is very suitable if the HTTP server hosts static JSON files. However, if the HTTP server uses a database or an external API to dynamically create JSON files, an extended data structure is useful. Therefore, it is possible to wrap any JSON data in a response object to have an unified root object and to provide advanced error handling. Please see this example code of a wrapped menu root object.

{
    "response": {
        "status": 200,
        "text": "OK",
        "message": null,
        "data": {
            "headline": "My Menu",
            "menu": [{
                    "label": "My Menu Item"
                }]
        }
    }
}

The next example code shows how an error response can look like.

{
    "response": {
        "status": 404,
        "text": "Not Found",
        "message": "Menu for database ID 'xyz' not found.",
        "data": null
    }
}

If you execute actions on server side, the server action response must always be wrapped in a response object. Please see the next example code of how a server action response can look like.

{
    "response": {
        "status": 200,
        "text": "OK",
        "message": null,
        "data": {
            "action": "menu:data",
            "data": {
                "headline": "My Menu",
                "menu": [{
                        "label": "My Menu Item"
                    }]
            }
        }
    }
}

Please see Actions#Server Actions for more information.

Property syntax of responses

Property	Type	Default Value	Mandatory	Since Version	Description
status	number	0	Yes	0.1.0	HTTP-compliant status code. This property must be set to 200 for success responses. Note: Error responses must also be sent as successful HTTP (2xx) responses. The actual error status code is provided in this property.
text	string	null	No	0.1.0	HTTP-compliant status text.
message	string	null	No	0.1.0	This property is only used in error responses and can be used to provide a detailed error description.
data	object	null	No	0.1.0	This property is only used in success responses and contains the actual JSON data.