From 9c15c96eb9890cc1329a62c0da993995fe1893f8 Mon Sep 17 00:00:00 2001 From: Teyras Date: Wed, 23 Nov 2016 20:05:49 +0100 Subject: [PATCH] wording --- Web-API.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/Web-API.md b/Web-API.md index 58d47c9..2ee6ca6 100644 --- a/Web-API.md +++ b/Web-API.md @@ -2,9 +2,20 @@ ## Description -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 is 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 cannot access information which are out of his authorization. +The Web API provides a controlled access to the evaluation backend. It also +enables the use of 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 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 +directly in the code, so that a user cannot access information which are out of +their authorization. ## Architecture @@ -13,8 +24,9 @@ Web API is written in PHP using [Nette framework](https://nette.org/en/). This f API architecture consists of several parts: - **router** -- component handling mapping from URL addresses to methods in presenter classes (called endpoints) -- **presenters** -- classes containing one method per endpoint responsible for fetching and parsing request arguments and performing desired action -- **entities** -- classes mirroring database tables, which are generated by ORM plugin +- **presenters** -- classes containing one method per endpoint responsible for + fetching and parsing request arguments and performing desired actions +- **entities** -- classes persisted using a database with an ORM framework - **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 @@ -52,7 +64,12 @@ 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 `. 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 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 [Doctrine](https://github.com/Kdyby/Doctrine) +[ORM](https://en.wikipedia.org/wiki/Object-relational_mapping) framework is used +as an object persistence layer. It provides simple to use annotations to specify +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.