DE EN EN (Google)

Retrieve messages

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

Get one or all messages.

Path parameters

id Message ID (integer, optional): if set, get message id

Query String

token Session token acquired with /api/v1/session

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

200 Success
400 API error: something is malformed
403 Not Authenticated: session is not authenticated
404 Message Not Found: message id not found
500 Server error: internal server error

Insert or update messages

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

Creates (PUT) or updates (POST) messages.

Query String

token Session token acquired with /api/v1/session

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

200 Success
400 API error: something is malformed
403 Not Authenticated: session is not authenticated
403 Change Owner On Creation: the user attempted to set a different owner than him-/herself when creating a message
404 Message Not Found: message message._id not found
404 User Not Found: user not found (in _owner.who)
404 Group Not Found: group not found (in _owner.who or _groups)
500 Server error: internal server error

Delete message

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

Path parameters

id Message ID (integer)

Query String

token Session token acquired with /api/v1/session

Authentication

This call requires the system.message system right.

Output

empty

Examples

Request:  DELETE /api/v1/message/32
Response: HTTP 200
200 Success
400 API error: something is malformed
403 Not Authenticated: session is not authenticated
404 Message Not Found: message id not found
500 Server error: internal server error