diff --git a/Web-API.md b/Web-API.md index c4e89da..e36cb4a 100644 --- a/Web-API.md +++ b/Web-API.md @@ -10,7 +10,7 @@ goes as HTTP(S) requests in predefined format, nowadays mostly known as Results from the API are in plain text in JSON format to be easily parsed in various languages (notably JavaScript). -This component must be publicly visible in the internet, so it is important to +This component must be publicly visible on the internet, so it is important to care about security and follow our recommendations. Security and user access restriction are among our primary concerns, so proper roles with permission separation are introduced and maintained. Also some additional checks are made @@ -32,7 +32,7 @@ API architecture consists of several parts: Each presenter method has several annotations. They are used for generating REST API documentation in [Swagger](http://swagger.io/), specifying request type and its parameters and specifying one level of access restrictions. Also, there is simple description of the endpoint. -For specifying the request type (_GET_, _POST_, _DELETE_) are used annotations with exactly these names without parameters. To describe request parameters is used `@Param` annotation with following arguments: +For specifying the request type (_GET_, _POST_, _DELETE_) annotations with exactly these names without any parameters are used. To describe request parameters `@Param` annotation is used with following arguments: - type -- the type of argument, one of _post_ of _query_ - name -- name of the argument (the key) @@ -41,7 +41,7 @@ For specifying the request type (_GET_, _POST_, _DELETE_) are used annotations w - required -- specifies if this option is mandatory (`true`, default) or optional (`false`) - description -- description for documentation of the API -Another annotation is `@LoggedIn` which takes no arguments. It can be placed before whole class or before a method, so requests from unauthorized users are forbidden. Permissions can be granted or prohibitted by `@UserIsAllowed` annotation. This one is only per method and takes one argument in format `key="value"`. The value specifies which action (_value_) of a resource (_key_) user need to be allowed to perform this request. Example how an annotated endpoint can look like: +Another annotation is `@LoggedIn` which takes no arguments. It can be placed before a whole class or before a method, so requests from unauthorized users are forbidden. Permissions can be granted or prohibitted by `@UserIsAllowed` annotation. This one is only per method and takes one argument in `key="value"` format. The value specifies which action (_value_) of a resource (_key_) the user needs to be allowed to perform this request. An example of how an annotated endpoint can look like: ```{.php} /** @@ -70,7 +70,7 @@ columns of database tables including types, indexes and also it is possible to make mapping between entities. For detailed info refer to [official documentation](http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/). -The API is capable of sending email messages. They can inform administrator about errors and users about submission evaluation or temporary link to change forgotten password. The [Nette Mail](https://doc.nette.org/en/2.4/mailing) extension provides nice interface for sending messages through external SMTP server (**preferred**) or builtin PHP function `mail`. It is important to set up the mailserver properly to ensure message delivery to the clients. The messages are rendered in HTML format via simple _Latte_ templates. +The API is capable of sending email messages. They can inform an administrator about errors and users about submission evaluation or a temporary link to change forgotten password. The [Nette Mail](https://doc.nette.org/en/2.4/mailing) extension provides nice interface for sending messages through external SMTP server (**preferred**) or builtin PHP function `mail`. It is important to set up the mailserver properly to ensure message delivery to the clients. The messages are rendered in HTML format via simple _Latte_ templates. ### Authentication @@ -90,16 +90,16 @@ completely instead of just receiving session data through a global variable. ## Installation -The web API requires a PHP runtime version at least 7. Which one depends on actual configuration, there is a choice between _mod_php_ inside Apache, _php-fpm_ with Apache or Nginx proxy or running it as standalone uWSGI script. Common thing is, that there are some PHP extensions, that have to be installed on the system. Namely ZeroMQ binding (`php-zmq` package or similar), MySQL module (`php-mysqlnd` package) and ldap extension module for CAS authentication (`php-ldap` package). Make sure that the extensions are loaded in your `php.ini` file (`/etc/php.ini` or files in `/etc/php.d/`). +The web API requires a PHP runtime version at least 7. Which one depends on actual configuration, there is a choice between _mod_php_ inside Apache, _php-fpm_ with Apache or Nginx proxy or running it as standalone uWSGI script. It is common that there are some PHP extensions, that have to be installed on the system. Namely ZeroMQ binding (`php-zmq` package or similar), MySQL module (`php-mysqlnd` package) and ldap extension module for CAS authentication (`php-ldap` package). Make sure that the extensions are loaded in your `php.ini` file (`/etc/php.ini` or files in `/etc/php.d/`). -The API depends on some other projects and libraries. For managing them is used [Composer](https://getcomposer.org/). It can be installed from system repositories or downloaded from the website, where are also detailed instructions. Composer reads `composer.json` file in project root and install dependencies to `vendor/` subdirectory. To do that, run: +The API depends on some other projects and libraries. For managing them [Composer](https://getcomposer.org/) is used. It can be installed from system repositories or downloaded from the website, where detailed instructions are as well. Composer reads `composer.json` file in the project root and installs dependencies to the `vendor/` subdirectory. To do that, run: ``` $ composer install ``` ## Configuration and usage -The API can be configured in `config.neon` and `config.local.neon` files in `app/config` directory. The first file is predefined by authors and should not be modified. The second one is not present and could be created from template `config.local.neon.example` in the config directory. Local configuration have higher precedence, so it will override default values from `config.neon`. +The API can be configured in `config.neon` and `config.local.neon` files in `app/config` directory. The first file is predefined by authors and should not be modified. The second one is not present and could be created from `config.local.neon.example` template in the config directory. Local configuration have higher precedence, so it will override default values from `config.neon`. ### Configurable items