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` ```json { "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](https://devdocs.foodsharing.network/code-review.html). ## TODO - [ ] endpoints that return a single object should not use wrappers around it (https://gitlab.com/foodsharing-dev/foodsharing/-/issues/511#note_179336151) - [x] make sure that status codes are used consistently through the endpoints (https://gitlab.com/foodsharing-dev/foodsharing/-/issues/511#note_308968630) and add them to the devdocs - [ ] consistent formatting / parsing of dates (https://gitlab.com/foodsharing-dev/foodsharing/-/issues/511#note_173339753) - [ ] use pagination where it makes sense (https://gitlab.com/foodsharing-dev/foodsharing/-/issues/511#note_173339753) (see also #971) - [x] 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](https://devdocs.foodsharing.network/docs/current/deployment/code-review/)