Retrieve messages

GET /api/v1/message[/<id>]?token=<token>

Get one or all messages.

Path parameters

Query String

Authentication

This call requires the system.message system right.

Output

Array of messages.

Examples

Request:  GET /api/v1/message
Response: HTTP 200
[
    {
        "_basetype": "message",
        "message": {
            "_id": 1,
            "_version": 1,
            "type": "welcome",
            "title": {
                "de-DE": "Willkommen!",
                "en-US": "Welcome!"
            },
            "confirmation": {
                "de-DE": "Bestätigung",
                "en-US": "confirm"
            },
            "start_time": {
                "value": "2000-01"
            },
            "end_time": {
                "value": "2020-01"
            }
        }
    },
    {
        "_basetype": "message",
        "message": {
            "_id": 2,
            "_version": 3,
            "type": "eula",
            "message_html": {
                "en-US": "<h1>End-user license agreement</h1>\n<p>This product...</p>"
            },
            "_groups": [
                {
                    "group": {
                        "_id": 3,
                        "displayname": {
                            "de-DE": "normale Nutzer",
                            "en-US": "normal users"
                        }
                    }
                }
            ]
        }
    }
]

Request:  GET /api/v1/message/9999
Response: HTTP 404
{
    "code": "server.not_found",
    "debugText": "message not found: 9999",
    "parameters": {
        "type": "message",
        "value": "9999"
    }
}

HTTP status codes

Insert or update messages

POST/PUT /api/v1/message?token=<token>

Creates (PUT) or updates (POST) messages.

Query String

Authentication

This call requires the system.message system right.

Input

Array of messages. POST only updates fields that are set, leaving the rest as they currently are.

Ouput

Array of messages that were updated.

Examples

Request:  PUT /api/v1/message
[
    {
        "message": {
            "_version": 1,
            "type": "eula",      // no ID is given
            "title": {
                "en-US": "EULA"
            }
        }
    }
]
Response: HTTP 200
[
    {
        "_basetype": "message",
        "message": {
            "_id": 32,           // ID is returned in the response
            "_version": 1,
            "type": "eula",
            "title": {
                "en-US": "EULA"
            }
        }
    }
]

Request:  POST /api/v1/message
[
    {
        "message": {
            "_id": 32,                          // ID must be provided
            "_version": 2,
            "title": {
                "de-DE": "Unsere Bedingungen",  // only given parameters will be updated
                "en-US": "Uur conditions"
            },
            "confirmation": {
                "en-US": "please confirm"
            }
        },
        "_groups": [
            {
                "group": {
                    "_id": 5
                }
            },
            {
                "group": {
                    "_id": 23
                }
            }
        ]
    }
]
Response: HTTP 200
[
    {
        "_basetype": "message",
        "message": {
            "_id": 32,
            "_version": 2,
            "type": "eula",
            "title": {
                "de-DE": "Unsere Bedingungen",
                "en-US": "Uur conditions"
            },
            "confirmation": {
                "en-US": "please confirm"
            }
        },
        "_groups": [
            {
                "group": {
                    "_id": 5,
                    "displayname": {
                        "de-DE": "Studenten",
                        "en-US": "students"
                    }
                }
            },
            {
                "group": {
                    "_id": 23,
                    "displayname": {
                        "de-DE": "Professoren",
                        "en-US": "professors"
                    }
                }
            }
        ]
    }
]

HTTP status codes

Delete message

DELETE /api/v1/message/<id>?token=<token>

Path parameters

Query String

Authentication

This call requires the system.message system right.

Output

empty

Examples

Request:  DELETE /api/v1/message/32
Response: HTTP 200