Responses

From MSX - Wiki
Jump to navigation Jump to search

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 response object
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.