The API is very important part of ReCodEx project. It provides common interface for usage in different user frontends such as default web application, mobile applications, commandline tools and possibly others. The communication goes as HTTP(S) requests in predefined format, nowadays mostly known as [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) format. Results from the API are in plain text in JSON format to be easily parsed in various languages (notably JavaScript).
The API is very important part of ReCodEx project. It provides common interface for usage in different user frontends such as default web application, mobile applications, commandline tools and possibly others. The communication goes as HTTP(S) requests in predefined format, nowadays mostly known as [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) format. 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's important to care about security and follow our recommendations. We have really focused on security aspect of the project, so proper roles with permission separation are introduced and maintained. Also some additional checks are made directly in the code, so user can't access informations which are out of his authorization.
This component must be publicly visible in the internet, so it's important to care about security and follow our recommendations. We have really focused on security aspect of the project, so proper roles with permission separation are introduced and maintained. Also some additional checks are made directly in the code, so user can't access information which are out of his authorization.
## Architecture
## Architecture
@ -18,7 +18,7 @@ API architecture consists of several parts:
- **repositories** -- common operations on entities of one type, mostly finding entity by identifier or persisting changes to the database
- **repositories** -- common operations on entities of one type, mostly finding entity by identifier or persisting changes to the database
- **helpers** -- set of classes solving more complicated internal logic, used from presenters to keep them reasonably small
- **helpers** -- set of classes solving more complicated internal logic, used from presenters to keep them reasonably small
Each presenter method has several annotations. They are used for generating REST API documentation in [Swagger](http://swagger.io/), specifying request type and it's parameters and specifying one level of access restrictions. Also, there is simple description of the endpoint.
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_) are used annotations with exactly these names without parameters. To describe request parameters is used `@Param` annotation with following arguments:
@ -52,7 +52,7 @@ public function actionCreateAccount() {
Authorization of users is based on validating his access token, which is obtained by users on successful login. This token has predefined validity period and has to be renewed before expiration to stay logged in. The token is sent to the API in HTTP Authorization header as value in format `Bearer <token>`. Requests with invalid or malformed token are treated as anonymous access with all its restrictions.
Authorization of users is based on validating his access token, which is obtained by users on successful login. This token has predefined validity period and has to be renewed before expiration to stay logged in. The token is sent to the API in HTTP Authorization header as value in format `Bearer <token>`. Requests with invalid or malformed token are treated as anonymous access with all its restrictions.
As [ORM](https://en.wikipedia.org/wiki/Object-relational_mapping) framework is used [Doctrine](https://github.com/Kdyby/Doctrine). It provides some simple to use annotations to specify collumns of database tables including types, indexes and also it's possible to make mapping between entities. For detailed info refer to [official documentation](http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/).
As [ORM](https://en.wikipedia.org/wiki/Object-relational_mapping) framework is used [Doctrine](https://github.com/Kdyby/Doctrine). It provides some simple to use annotations to specify columns of database tables including types, indexes and also it's 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's 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 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's 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.
@ -85,7 +85,7 @@ Description of configurable items. All timeouts are in milliseconds if not state
- monitor -- connection to monitor
- monitor -- connection to monitor
- address -- URI of monitor
- address -- URI of monitor
- CAS -- CAS external authentication
- CAS -- CAS external authentication
- serviceId -- identifier of this service for public
- serviceId -- visible identifier of this service
- ldapConnection -- parameters for connecting to LDAP, _hostname_, _base_dn_, _port_, _security_ and _bindName_
- ldapConnection -- parameters for connecting to LDAP, _hostname_, _base_dn_, _port_, _security_ and _bindName_
- fields -- names of LDAP keys for informations as _email_, _firstName_ and _lastName_
- fields -- names of LDAP keys for informations as _email_, _firstName_ and _lastName_
- emails -- common configuration for sending email (addresses and template variables)
- emails -- common configuration for sending email (addresses and template variables)
@ -109,7 +109,7 @@ Description of configurable items. All timeouts are in milliseconds if not state
- secure -- security, values are empty for no security, "ssl" or "tls"
- secure -- security, values are empty for no security, "ssl" or "tls"
- context -- additional parameters, depending on used mail engine. For examle self-signed certificates can be allowed as _verify_peer_ and _verify_peer_name_ to false and _allow_self_signed_ to true under _ssl_ key (see example).
- context -- additional parameters, depending on used mail engine. For examle self-signed certificates can be allowed as _verify_peer_ and _verify_peer_name_ to false and _allow_self_signed_ to true under _ssl_ key (see example).
Outside the parameters section of configuration is configuration for Doctrine. It's ORM framework which mappes PHP objects (entities) into database tables and rows. The configuration is simple, required items are only _user_, _password_ and _host_ with _dbname_, i.e. address of database computer (mostly localhost) with name of ReCodEx database.
Outside the parameters section of configuration is configuration for Doctrine. It's ORM framework which maps PHP objects (entities) into database tables and rows. The configuration is simple, required items are only _user_, _password_ and _host_ with _dbname_, i.e. address of database computer (mostly localhost) with name of ReCodEx database.