request handling analysis

Rewritten-docs.md

@@ -1463,7 +1463,23 @@ a Nette extension which makes integartion of Doctrine 2 very straightforward.
 
 #### Request handling
 
-@todo Nette Router, how we exploit presenters to act as api endpoints
+A typical scenario for handling an API request is matching the HTTP request with
+a corresponding handler routine which creates a response object, that is then
+sent back to the client, encoded with JSON. The Nette\Application package can be
+used to achieve this with Nette, although it is meant to be used mainly in MVP
+applications.
+
+Matching HTTP requests with handlers can be done using standard Nette URL
+routing -- we will create a Nette route for each API endpoint. Using the routing
+mechanism from Nette logically leads to implementing handler routines as Nette
+Presenter actions. Each presenter should serve logically related endpoints.
+
+The last step is encoding the response as JSON. In Nette\Application, HTTP
+responses are returned using the `Presenter::sendResponse()` method. We decided
+to write a method that calls `sendResponse` internally and takes care of the
+encoding. This method has to be called in every presenter action. An alternative
+approach would be using the internal payload object of the presenter, which is
+more convenient, but provides us with less control.
 
 #### Authentication
 
@@ -1485,11 +1501,9 @@ thanks to the simple authentication flow. Replacing these services in a Nette
 application is also straightforward, thanks to its dependency injection
 container implementation.
 
-@todo: what files are stored in api, why there are duplicates among api and fileserver
-
 #### Uploading files
 
-There are two cases when users need to upload files using the API -– submitting
+There are two cases when users need to upload files using the API -- submitting
 solutions to an assignment and creating a new exercise. In both of these cases,
 the final destination of the files is the fileserver. However, the fileserver is
 not publicly accessible, so the files have to be uploaded through the API.