API - reasons for Nette

Rewritten-docs.md

@@ -1453,8 +1453,9 @@ of connection with no message loss.
 ### API server
 
 The API server must handle HTTP requests and manage the state of the application
-in some kind of a database. It must also be able to communicate with the backend
-over ZeroMQ.
+in some kind of a database. The API server will be a RESTful service and will
+return data encoded as JSON documents. It must also be able to communicate with
+the backend over ZeroMQ.
 
 We considered several technologies which could be used:
 
@@ -1489,13 +1490,24 @@ any need for changing the code. MariaDB was chosen as the storage backend.
 
 To speed up the development process of the PHP server application we decided to
 use a web framework. After evaluating and trying several frameworks, such as
-Lumen, Laravel, and Symfony, we ended up using Nette. This framework is very
-common in Czech Republic -- its lead developer is a well-known Czech programmer
-David Grudl -- and we were already familiar with the patterns used in this
-framework, such as dependency injection, authentication, routing. These concepts
-are useful even when developing a REST application, which might be a surprise
-considering that Nette focuses on "traditional" web applications. There is also
-a Nette extension which makes integration of Doctrine 2 very straightforward.
+Lumen, Laravel, and Symfony, we ended up using Nette.
+
+- **Lumen** and **Laravel** seemed promissing but the default ORM framework
+  Eloquent is an implementation of ActiveRecord which we wanted to avoid. It
+  was also suprisingly complicated to implement custom middleware for validation
+  of access tokens in the headers of incoming HTTP requests.
+- **Symfony** is a very good framework and has Doctrine "built-in". The reason
+  why we did not use Symfony in the end was our lack of experience with this
+  framework.
+- **Nette framework** is very popular in the Czech Republic -- its lead
+  developer is a well-known Czech programmer David Grudl. We were already
+  familiar with the patterns used in this framework, such as dependency
+  injection, authentication, routing. These concepts are useful even when
+  developing a REST application which might be a surprise considering that
+  Nette focuses on "traditional" web applications. 
+  Nette is inspired by Symfony and many of the Symfony bundles are available
+  as components or extensions for Nette. There is for example a Nette
+  extension which makes integration of Doctrine 2 very straightforward.
 
 #### Architecture of the system