REST API

The more modern way to build our api is a REST api by FOS (friends of symfony). The documentation of the REST api endpoints is located at the definition of the endpoints and can be nicely viewed on (https://beta.foodsharing.de/api/doc/).

In the documentation you can read how to properly include the documentation. A good example can be found in /src/Controller/ForumRestController.php.

In the Code quality page we have some notes on how to define the REST API Endpoints.

The javascript code that sends REST API requests is found under /client/src/api and is used by other javascript by import.

All php classes working with REST requests are found in /src/Modules/Controllers/<..>RestController.php. This is configured in /config/routes/routing.yml. There it is also configured, that calls to /api/ are interpreted by the REST api, e.g.

https://foodsharing.de/api/conversations/<conversationid>

This is being called when you click on a conversation on the „Alle Nachrichten“ page.

REST is configured via annotations in comments in functions.

  • @Rest\Get("subsite") specifies the address to access to start this Action: `https://foodsharing.de/api/subsite"
  • @Rest\QueryParam(name="optionname") specifies which options can be used. These are found behind the ? in the url: http://foodsharing.de/api/conversations/687484?messagesLimit=1 only sends one message.
  • Both Get and QueryParam can enforce limitations on the sent data with requirement="<some regular expression>".
  • @SWG\Parameter, @SWG\Response, ... create the documentation (see above)

Functions need to have special names for symfony to use them: the end with Action. They start with a permission check, throw a HttpException(401) if the action is not permitted. Then they somehow react to the request, usually with a Database query via the appropriate Model or Gateway classes.

During running php, the comments get translated to convoluted php code. REST also takes care of the translation from php data structures to json. This json contains data. Errors use the error codes of http-requests.

While reading and writing code a (basic) manual and an annotation overview will help.