Define a ruleset for REST API Endpoints

currently we have already implemented some API Endpoints where responses are basically the same data from the database/gateway passed through the RestController, without changing it's pretty badly styled data structure

GET /api/conversations

{
    "id": "412072",
    "last": "2019-02-01 10:36:58",
    "lastTimestamp": "1551433018",
    "member": [
        {
            "id": "101",
            "name": "Bodhi",
            "photo": "94507227296c5e2edd9fa3afa4ff2cae.jpg",
            "gender": "1"
        }
    ],
    "lastMessage": "Liebes Testbetrieb [...]",
    "lastFoodsaverId": "252584",
    "unread": "1",
    "name": "Team Testbetrieb 332"
}

since multiple projects (mobile apps) start to rely on this data, it get's more and more difficult to change such formats afterwards without braking them, so I think we should define a ruleset of how we style the API requests and responses.

This issue is meant as an place for discussion about rules, which we could then update in the devdocs.

TODO

• endpoints that return a single object should not use wrappers around it (#511 (comment 179336151))
• make sure that status codes are used consistently through the endpoints (#511 (comment 308968630)) and add them to the devdocs
• consistent formatting / parsing of dates (#511 (comment 173339753))
• use pagination where it makes sense (#511 (comment 173339753)) (see also #971)
• Consistently return 401 if the user is not logged in. Use 403 if the user is logged in but lacks permission to do something.
• All exceptions should be thrown with a text message
• Add rate limiting (https://symfony.com/doc/current/rate_limiter.html)
• Be consistent with singular/plural in the endpoints' paths

collected thoughts

Are moved to the Devdocs