Welcome to SAM API’s Documentation

Welcome to SAM API’s documentation. This document is aimed at developers and it is highly recommended to start with the Installation section and then go forward with the API sections. The main purpose of this documentation is to provide insights into how one should use SAM’s core API services in the development of a frontend (e.g., the default one provided at https://github.com/SECURIoTESIGN/SAM).

Project Overview

Security Advising Modules (SAM) is a framework that aggregates and connects all the various modules developed under the scope of the SECURIoTESIGN project while providing a graphical interface to interact with them. SAM is modular, allowing for both quick integrations of newly developed modules and updates to existing modules. SAM works as a personal security assistant, more relatable, and capable of communicating with the end-user through a series of easily understandable questions, which the user can answer directly or through a set of predefined answers.

Installation

The installation, for development proposes only, can be accomplished through a group of Docker containers.

1. Clone the public repository.

2. Create the API and database docker imagens and subsequent containers:

cd sam-api
make

Note

The database and API container will be deployed with API port set to 8080 and database port set to 3306. The database user will be root and the password secure.

3. Deploy the database into the database container:

sudo docker exec -it sam-db python3 install_db.py

You can access the database using DBeaver or similar (use sudo docker inspect sam-db to get the IP of the sam-db container).

4. Develop away!

You can start both containers as follows:

sudo docker stop sam-api && sudo docker start sam-api

SAM’s REST services can be tested and accessed through insomnia – The Insomnia JSON file of this project can be found on the following link.

Important

The contents of folder sam-api are mapped to the sam-api container, any local changes will be reflected.

Core and Community Modules/Plugins

Several module and plugins have been developed by the SECURIoTESIGN team and the community. Namely:

• Security Requirements Elicitation (SRE) - This module will elicit the main security requirements and properties, e.g., confidentiality, integrity, authentication, access control, availability or accountability that the system should implement from the basic information of what composes it and defines it (e.g., type of system, methods of authentication, types of users, sensitive information storage).

• Security Best Best Practices (SBPG) - This module will provide best practices guildelines that will highlight common potential vulnerabilities that need to be taken into account during development, and provide information on secure practices that should be implemented.

• Lightweight Criptographic Algorithms Recommendation (LWCAR) - This module will take the information on the system hardware requirements and defined security requirements. It also proposes algorithms that can be implemented to ensure the security requirements are fulfilled. It specifically recommends lightweight cryptographic algorithms, for both software and hardware implementations.

• Threat Modeling Solution (TMS) - This modules provides a set of threats that based on the answers given by a user.

• Assessment of the Correct Integration of Security Mechanisms (ACISM) - This module outputs system tests to check for the presence of threats.

These modules can be found at https://github.com/SECURIoTESIGN/SAM-Modules.

Important

A module is defined as a component that incorporates questions and answers and an output designated as recommendations, while a plugin is a special module similar to the latter but it only provides the output (i.e., recommendations) – These plugins are dependent on the input of other modules.

Installing Core Modules

To install core modules into SAM:

cd sam-api
make modules

Important

Beware, this process will recreate SAM’s database - All data will be lost!

Developing Modules

The development of modules can be accomplished by using the services detailed in section Modules Services API. If there is a need to develop modules with some logic – that is, without being dependent on the mapping between question, answer, and recommendation provided by core services – an example is available on the following link.

Note

If a logic file is developed for a module those services detailed in section Add module should be used in conjuntion with the file API detailed in Upload File.

Statistics Services API

This section includes details concerning services developed for the statistic entity implemented in

statistic.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
from api import app, mysql
from flask import request
import views.user, modules.utils, views.recommendation, views.module, views.session


"""
[Summary]: Get Global Stats
[Returns]: Response result.
"""
@app.route("/api/statistics", methods=['GET'])
def get_global_stats():
    if request.method != 'GET': return
    
    views.user.isAuthenticated(request)

    stats = {}
    tmp_users = get_number_of_table('user')
    tmp_modules = get_number_of_table('module')
    tmp_questions = get_number_of_table('question')
    tmp_answers = get_number_of_table('answer')
    tmp_sessions = get_number_of_table('session')
    tmp_recommendations = get_number_of_table('recommendation')

    stats['users']              = tmp_users or 0
    stats['modules']            = tmp_modules or 0
    stats['questions']          = tmp_questions or 0
    stats['answers']            = tmp_answers or 0
    stats['sessions']           = tmp_sessions or 0
    stats['recommendations']    = tmp_recommendations or 0

    # 'May the Force be with you.'
    return(modules.utils.build_response_json(request.path, 200, stats)) 

"""
[Summary]: Get the number of users 
[Returns]: Response result.
"""
@app.route("/api/statistic/users", methods=['GET'])
def get_stats_user(internal_call=False):
    if (not internal_call): 
        if request.method != 'GET': return
    
    # Check if the user has permissions to access this resource
    if (not internal_call):
        views.user.isAuthenticated(request)
    
    # Let's get the info from the databse.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT COUNT(id) as size FROM user")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        data = {}
        for row in res:
            data['size'] = row[0]
            break
    
    cursor.close()
    conn.close()

    # 'May the Force be with you, young master'.
    if (not internal_call):
        return(modules.utils.build_response_json(request.path, 200, data)) 
    else:
        return(data)
"""
[Summary]: Get the number of modules 
[Returns]: Response result.
"""
@app.route("/api/statistic/modules", methods=['GET'])
def get_stats_modules(internal_call=False):
    if (not internal_call): 
        if request.method != 'GET': return
    
    # Check if the user has permissions to access this resource
    if (not internal_call):
        views.user.isAuthenticated(request)
    
    # Let's get the info from the databse.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        # Top 5 only
        cursor.execute("SELECT shortname, displayname, occurrences FROM module, (SELECT moduleID as mID, count(*) as occurrences FROM session GROUP BY moduleID ORDER BY occurrences DESC LIMIT 5) as Top5 WHERE ID = mID")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, {"size":0}))
        else:
            return(None)
    else:
        tot_mod = 0
        stat = {}
        stat['top'] = []
        for row in res:
            module = {}
            module['shortname'] = row[0]
            module['displayname'] = row[1]
            module['occurrences'] = row[2]
            tot_mod += row[2]
            stat['top'].append(module)
        
        stat['size'] = tot_mod

    cursor.close() 
    conn.close()

    # 'May the Force be with you, young master'.
    if (not internal_call):
        return(modules.utils.build_response_json(request.path, 200, stat))
    else: 
        print("--->" + stat)
        return(stat)

"""
[Summary]: Get the number of questions 
[Returns]: Response result.
"""
@app.route("/api/statistic/questions", methods=['GET'])
def get_stats_questions(internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # Check if the user has permissions to access this resource
    if (not internal_call):
        views.user.isAuthenticated(request)
    
    # Let's get the info from the databse.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT COUNT(id) as size FROM question")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None) 
    else:
        data = {}
        for row in res:
            data['size'] = row[0]
            break
    
    cursor.close()
    conn.close()

    # 'May the Force be with you, young master'.
    if (not internal_call):
        return(modules.utils.build_response_json(request.path, 200, data))
    else:
        return(data)

"""
[Summary]: Get the number of answers 
[Returns]: Response result.
"""
@app.route("/api/statistic/answers", methods=['GET'])
def get_stats_answers(internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return
    # Check if the user has permissions to access this resource
    if (not internal_call):
        views.user.isAuthenticated(request)
    
    # Let's get the info from the databse.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT COUNT(id) as size FROM answer")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else: 
            return(None)
    else:
        data = {}
        for row in res:
            data['size'] = row[0]
            break
    
    cursor.close()
    conn.close()
    # 'May the Force be with you, young master'.
    if (not internal_call):
        return(modules.utils.build_response_json(request.path, 200, data))
    else:
        return(data)

"""
[Summary]: Get the number of recommendations 
[Returns]: Response result.
"""
@app.route("/api/statistic/recommendations", methods=['GET'])
def get_stats_recommendations(internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return
    # Check if the user has permissions to access this resource
    if (not internal_call):
        views.user.isAuthenticated(request)
    
    # Let's get the info from the databse.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        # Top 5 only
        cursor.execute("SELECT content, occurrences FROM recommendation, (SELECT recommendationID as rID, count(*) as occurrences FROM session_recommendation GROUP BY recommendationID ORDER BY occurrences DESC LIMIT 5) as Top5 WHERE ID = rID;")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, {"size":0}))
        else:
            return(None)
    else:
        tot_recm = 0
        stat = {}
        stat['top'] = []
        for row in res:
            recommendation = {}
            recommendation['occurrences'] = row[1]
            recommendation['content'] = row[0]
            tot_recm += row[1]
            stat['top'].append(recommendation)
        
        stat['size'] = tot_recm

    cursor.close()
    conn.close()
    # 'May the Force be with you, young master'.
    if (not internal_call):
        return(modules.utils.build_response_json(request.path, 200, stat))
    else:
        return(stat)


"""
[Summary]: Get the number of sessions in the last 7 days.
[Returns]: Response result.
"""
@app.route("/api/statistic/sessions", methods=['GET'])
def get_stats_sessions(internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return
    # Check if the user has permissions to access this resource
    if (not internal_call):
        views.user.isAuthenticated(request)
    
    # Let's get the info from the databse.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        # Number of session in the Last 7 days sessions
        cursor.execute("SELECT date(createdOn) as day, COUNT(*) as occurrences FROM session WHERE createdon >= DATE_ADD(CURDATE(), INTERVAL -7 DAY) GROUP BY day")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, {"size": 0}))
        else:
            return(None)   
    else:
        stat = {}
        stat['top'] = []
        for row in res:
            date = {}
            date['date'] = row[0]
            date['occurrences'] = row[1]
            stat['top'].append(date)

    cursor.close()
    conn.close()

    # 'May the Force be with you, young master'.
    if (not internal_call):
        return(modules.utils.build_response_json(request.path, 200, stat))
    else:
        return(stat)


"""
[Summary]: Get the amount of elements in a table. 
[Returns]: Integer.
"""
def get_number_of_table(table_name):
    size = 0
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT COUNT(id) as size FROM "+str(table_name))
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    if len(res) != 0:
            size = res[0][0]

    return(size)

GET /api/statistics

Synopsis

Get the global statistics of the plataform.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• answers (int) – The total number of responses.

• modules (int) – The total number of modules.

• recommendations (int) – The total number of recommendations.

• sessions (int) – The total number of sessions executed by users.

• users (int) – The total number of registered users.

• status (int) – Status code.

Status Codes

• 200 OK – Statistics successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve statistics.

Example Response

{
   "/api/statistics":{
      "users":2
      "modules":2,
      "questions":30,
      "answers":60,
      "recommendations":10,
      "sessions":2,
      "status":200,
   }
}

---

GET /api/statistic/users

Synopsis

Get the total number of users of the platform.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• size (int) – The total number of registered users.

Status Codes

• 200 OK – Statistics successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve statistics.

Example Response

{"/api/statistic/users":{"size":2, "status":200}}

---

GET /api/statistic/modules

Synopsis

Get the total number of modules of the platform.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• size (int) – The total number of modules.

• top (array) – An array that contains the topmost used modules.

• status (int) – Status code.

Status Codes

• 200 OK – Statistics successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve statistics.

Example Response

{
   "/api/statistic/modules":{
      "size":2,
      "top":[
         {
            "shortname":"SRE"
            "displayname":"Security Requirements",
            "occurrences":2,
         }
      ],
      "status":200
   }
}

---

GET /api/statistic/questions

Synopsis

Get the total number of questions of the platform.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• size (int) – The total number of questions.

• status (int) – Status code.

Status Codes

• 200 OK – Statistics successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve statistics.

Example Response

{"/api/statistic/questions":{"size":30, "status":200}}

---

GET /api/statistic/answers

Synopsis

Get the total number of answers of the platform.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• size (int) – The total number of answers.

• status (int) – Status code.

Status Codes

• 200 OK – Statistics successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve statistics.

Example Response

{"/api/statistic/answers":{"size":60, "status":200}}

---

GET /api/statistic/recommendations

Synopsis

Get the total number of recommendations of the platform.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• size (int) – The total number of recommendations.

• top (array) – An array that contains the topmost given recommendations.

• status (int) – Status code.

Status Codes

• 200 OK – Statistics successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve statistics.

Example Response

{
   "/api/statistic/recommendations":{
      "size":10,
      "top":[
         {
            "content":"Confidentiality",
            "occurrences":2
         }
      ],
      "status":200
   }
}

---

GET /api/statistic/sessions

Synopsis

Get the total number of sessions per day created by users of the platform.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• top (array) – An array that contains the number of sessions per day.

• status (int) – Status code.

Status Codes

• 200 OK – Statistics successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve statistics.

Example Response

{
   "/api/statistic/sessions":{
      "top":[
         {
            "date":"Sat, 20 Nov 2021 00:00:00 GMT",
            "occurrences":2
         }
      ],
      "status":200
   }
}

Authentication Services API

This section includes details concerning services developed for the authentication entity implemented in

user.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
import json, jwt, ast
from api import app, mysql, JWT_SECRET_TOKEN, JWT_EXPIRATION_SECONDS, RECAPTCHA_SECRET
from email_validator import validate_email, EmailNotValidError
from flask import request
from datetime import datetime
import requests
from datetime import timedelta
import modules.error_handlers, modules.utils # SAM's modules

"""
[Summary]: User Authentication Service (i.e., login).
[Returns]: Returns a JSON object with the data of the user including a JWT authentication token.
"""
@app.route('/api/user/login', methods=['POST'])
def login_user():
    if request.method == "POST":
        # 1. Validate and parse POST data.
        if not request.form.get('email'):
            raise modules.error_handlers.BadRequest(request.path, 'The email cannot be empty', 400) 
        if not request.form.get('psw'):
            raise modules.error_handlers.BadRequest(request.path, 'The password cannot be empty', 400) 
        
        email   = request.form['email']
        psw     = request.form['psw']

        # 2. Connect to the DB and get the user info.
        try:
            conn    = mysql.connect()
            cursor  = conn.cursor()
            cursor.execute("SELECT ID, email, psw, avatar, administrator FROM user WHERE email=%s", email)
        except Exception as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
        # 2.1. Check if the user exists.
        if (cursor.rowcount == 0): 
            raise modules.error_handlers.BadRequest(request.path, "A user with the specified email was not found", 404) 
        
        # 2.2. Process the DB results.
        records = cursor.fetchall()
        dbpsw = ""
        data = {} # Create a new nice empty dictionary to be populated with data from the DB.
        for row in records:
            data['id']          = row[0]
            data['email']       = row[1]
            # For security reasons lets not store the password in the dic.
            dbpsw               = row[2] 
            data['avatar']      = row[3]
            data['is_admin']    = row[4]
            # Set the expiration time of the token, the JWT auth token will not be valid after x seconds
            # Default is a 15 minute session
            data['exp']     = datetime.utcnow() + timedelta(seconds=int(JWT_EXPIRATION_SECONDS))

        cursor.close()
        conn.close()    
        
        # Check if the hashed password of the database is the same as the one provided by the user.
        if modules.utils.check_password(dbpsw, psw):
            # First, build the authentication token and added it to the dictionary.
            # Second, let's create a JSON response with the data of the dictionary.
            data['token'] = (jwt.encode(data, JWT_SECRET_TOKEN, algorithm='HS256')).decode('UTF-8')
            
            # Authentication success, the user 'can follow the white rabbit'.
            return (modules.utils.build_response_json(request.path, 200, data))
        else:
            raise modules.error_handlers.BadRequest(request.path, "Authentication failure", 401)

"""
[Summary]: Clear the list of expired blacklisted JSON Web Tokens of a user.
[Arguments]:
       - $userID$: Target user.
[Returns]: Returns false, if an error occurs, true otherwise. 
"""
def clear_expired_blacklisted_JWT(userID):
    debug=False
    if (debug): print("Checking blacklisted tokens for user id ="+str(userID))
    try:
        # Check if this user id exists.
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT token FROM auth_token_blackList WHERE userID=%s", userID)
        res = cursor.fetchall()
    except Exception as e:
        if (debug): print(str(e))
        return (False) # 'Houston, we have a problem.'
    # Empty results ?
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return (True)
    else:
        i=0
        for row in res: 
            token = row[0]
            if (debug): print ("# Checking token[" + str(i) + "]" + "= " + token)
            i = i + 1
            try:
                # Let's see if the token is expired
                res_dic  = jwt.verify(token)
                if (debug): print(" - The token is still 'alive'. Nothing to do here.")
            except:
                if (debug): print(" - The token is expired, removing it from the database for user with id " + str(userID))
                # The token is expired, remove it from the DB
                try:
                    cursor.execute("DELETE FROM auth_token_blacklist WHERE token=%s AND userID=%s", (token,userID))
                    conn.commit()
                except Exception as e:
                    if (debug): print(str(e))
                    return (False) # 'Houston, we have a problem.'
    return(True)

"""
[Summary]: Performs a logout using an JWT authentication token.
[Returns]: 200 response if the user was successfully logged out.
[ref]: Based on https://medium.com/devgorilla/how-to-log-out-when-using-jwt-a8c7823e8a6
"""
@app.route('/api/user/logout', methods=['POST'])
def logout_user():
    debug = True
    
    data = {}
    if request.method != "POST": return
    # 1. Check if the token is available on the request header.
    headers = dict(request.headers)
    if (debug): print(str(len(headers)))
    
    # 2. Check if the Authorization header name was parsed.
    if 'Authorization' not in headers: raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the permission to access this resource. Please, provide an authorization token.", 403) 
    token_parsed = headers['Authorization']
    if ("Bearer" in token_parsed):
        token_parsed = (token_parsed.replace("Bearer", "")).replace(" ", "")
   
    if (debug): print("Parsed Token:" + token_parsed)
    
    try:
        # 3. From now on the token will be blacklisted because the user has logout and the token may still
        #    exists somewhere because its expiration date is still valid.
        
        # 3.1. Let's clean the house - Remove possible expired tokens from the user of the token
        res_dic  = jwt.decode(token_parsed, JWT_SECRET_TOKEN, algorithms=['HS256'])
       
        userID = int(res_dic['id'])
        if not clear_expired_blacklisted_JWT(userID): # Sanity check
            return (modules.utils.build_response_json(request.path, 500))
        # 3.2. Let's add the token to the blacklist table on the database for the current user
        #      That is, blacklist the current token, that may or may not be alive. 
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("INSERT INTO auth_token_blacklist (userID, token) VALUES (%s, %s)", (userID, token_parsed))
        conn.commit()
        data['message'] = "The authentication token was blacklisted. The user should now be logouted on the client side."
       
    except jwt.exceptions.ExpiredSignatureError as e:
        # We don't need to blacklist this token, the token is already expired (see 'exp' field of the JWT defined in the authenticate function).
        # raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
        data['message'] = "The token has already expired, no need to blacklist it. The user should now be logouted on the client side."
        return (modules.utils.build_response_json(request.path, 200, data))
    except Exception as e :
        # Double token entry ?
        if e.args[0] == 1062:
            data['message'] = "The token was already blacklisted. The user should now be logouted on the client side."
        else:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        try:
            cursor.close()
            conn.close()
        except:
            pass # cursor or conn may not be defined, I don't care, 'Just keep swimming'.
    #
    return (modules.utils.build_response_json(request.path, 200, data))

@app.route('/api/user/<email>/admin', methods=['GET'])
def is_admin(email):
    if request.method != 'GET': return
    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)

    # 2. Let's get the groups associated with the parsed user.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT email, administrator FROM user WHERE email=%s AND administrator=1", email) 
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 

    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 200, {"admin": 0})) 
    else:
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, {"admin": 1}))
"""
[Summary]: User Registration Service (i.e., add a new user).
[Returns]: Returns a JSON object with the data of the user including a JWT authentication token.
"""
@app.route('/api/user', methods=['POST'])
def add_user():
    if request.method != 'POST': return

    # 1. Let's get our shiny new JSON object and current time.
    # - Always start by validating the structure of the json, if not valid send an invalid response.
    try:
        obj = request.json
        obj=ast.literal_eval(str(obj).lower())

        date = (datetime.now()).strftime('%Y-%m-%d %H:%M:%S')
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 

    # 2. Let's validate the data of our JSON object with a custom function.
    if (not modules.utils.valid_json(obj, {"email", "psw", "firstname", "lastname", "avatar", "g-recaptcha-response"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)

    if ("insomnia" not in request.headers.get('User-Agent')):
        # 3. Validate reCAPTCHA
        if not is_human(obj['g-recaptcha-response']):
            raise modules.error_handlers.BadRequest(request.path, "reCAPTCHA failure - Bots are not allowed.", 400)

    # 4. Let's hash the hell of the password.
    hashed_psw = modules.utils.hash_password(obj['psw'])
    obj['psw'] = "" # "paranoic mode".
    
    # 5. Check if the user was not previously registered in the DB (i.e., same email)
    if (find_user(obj['email']) is not None):
        raise modules.error_handlers.BadRequest(request.path, "The user with that email already exists", 500)

    # 6. Connect to the database and create the new user.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        print(obj)
        print(hashed_psw)
        cursor.execute("INSERT INTO user (email, psw, firstName, lastName, avatar, createdon, updatedon) VALUES (%s, %s, %s, %s, %s, %s, %s)", (obj['email'], hashed_psw, obj['firstname'], obj['lastname'], obj['avatar'], date, date))
        conn.commit()
    except Exception as e:
        print("--->" +str(e))
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 7. Authentication success, the user can now choose to 'take the red or blue pill to follow the white rabbit'
    return (modules.utils.build_response_json(request.path, 200))

"""
[Summary]: Get users.
[Returns]: Returns a User object.
"""
# Check if a user exists
@app.route('/api/users', methods=['GET'])
def get_users():
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)
    
    # 3. Let's get users from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, email, firstName, lastName, avatar, userStatus, administrator, createdon, updatedon FROM user")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Empty results ?
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] 
        for row in res:
            data = {}
            data['id']          = row[0]
            data['email']       = row[1]
            data['firstName']   = row[2]
            data['lastName']    = row[3]
            data['avatar']      = row[4]
            data['user_status']  = row[5]
            data['administrator'] = row[6]
            data['createdon']   = row[7]
            data['updatedon']   = row[8]
            datas.append(data)
        cursor.close()
        conn.close()
        # 4. Return information about the user (except the password) and 'May the Force be with you'.
        return(modules.utils.build_response_json(request.path, 200, datas))    

"""
[Summary]: Finds a user by email.
[Returns]: Returns a User object.
"""
# Check if a user exists
@app.route('/api/user/<email>', methods=['GET'])
def find_user(email, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    if (not internal_call):
        isAuthenticated(request)
       
    # 2. Let's validate the email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(email)
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 
    
    # 3. Let's get the user from the database with the provided [email].
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, email, firstName, lastName, avatar FROM user WHERE email=%s", email)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Empty results ?
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        data = {} # Create a new nice empty dictionary to be populated with data from the DB.
        for row in res:
            data['id']          = row[0]
            data['email']       = row[1]
            data['firstName']   = row[2]
            data['lastName']    = row[3]
            data['avatar']      = row[4]
        cursor.close()
        conn.close()

        # 4. Return information about the user (except the password) and 'May the Force be with you'.
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, data))
        else:
            return(data)

"""
[Summary]: Delete a user
[Returns]: Returns a success or error response
"""
@app.route('/api/user/<email>', methods=["DELETE"])
def delete_user(email):
    if request.method != 'DELETE': return
    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)
  
    # 2. Let's validate the email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(email)
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 

    # 3. Connect to the database and delete the user
    # TODO: Let's build procedures in the DB to delete Users. 
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM user WHERE email=%s", email)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 4. The Delete request was a success, the user 'took the blue pill'.
    return (modules.utils.build_response_json(request.path, 200))

"""
[Summary]: Updates a user
[Returns]: Returns a success or error response
"""
@app.route('/api/user/<email>', methods=["PUT"])
def update_user(email):
    updatePsw = False
    # Note: Remember that if an email is being changed, the email argument is the old one; 
    #       The new email content is available on the JSON object parsed in the body of the request.  
    if request.method != 'PUT': return
    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)

    # 2. Let's validate the email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(email)
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 

    # 3. Let's get our shiny new JSON object and current time.
    # - Always start by validating the structure of the json, if not valid send an invalid response.
    try:
        obj = request.json
        date = (datetime.now()).strftime('%Y-%m-%d %H:%M:%S')
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 


    # 4. Let's validate the data of our JSON object with a custom function.
    if (not modules.utils.valid_json(obj, {"email", "avatar", "firstname", "lastname"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)

    # 4.1. Let's also validate the new email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(obj['email'])
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 

    # 5. Hash the new password and store it (if supplied)
    if (modules.utils.valid_json(obj, {"psw"})):
        updatePsw=True
        hashed_psw = modules.utils.hash_password(obj['psw'])
        obj['psw'] = "" # "paranoic mode".

    # 6. Connect to the database and update the user with the data of the parsed json object
    # TODO: - Let's build procedures in the DB to update Users. 
    #       - Let's not update every single field of the User, instead, let's just updated the one that has changed.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        if (updatePsw):
            cursor.execute("UPDATE user SET email=%s, psw=%s, firstName=%s, lastName=%s, avatar=%s, updatedOn=%s WHERE email=%s",  (obj['email'], hashed_psw, obj['firstname'], obj['lastname'], obj['avatar'],date,email))
        else:
            cursor.execute("UPDATE user SET email=%s, firstName=%s, lastName=%s, avatar=%s, updatedOn=%s WHERE email=%s",  (obj['email'], obj['firstname'], obj['lastname'], obj['avatar'],date,email))    
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 4. The Update request was a success, the user 'is in the rabbit hole'
    return (modules.utils.build_response_json(request.path, 200))

"""
[Summary]: Finds groups of a user.
[Returns]: Returns a success or error response
"""
@app.route('/api/user/<email>/groups', methods=["GET"])
def find_user_groups(email):
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)
       
    # 2. Let's validate the email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(email)
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 
    
    # 3. Let's get the user from the database with the provided [email].
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT user_id, user_email, user_group FROM view_user_group WHERE user_email=%s", email)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Empty results ?
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = []
        for row in res:
            data = {} # Create a new nice empty dictionary to be populated with data from the DB.
            data['user_id']     = row[0]
            data['user_email']  = row[1]
            data['user_group']  = row[2]
            datas.append(data)
        cursor.close()
        conn.close()
        # 4. Return information about the user (except the password) and 'May the Force be with you'.
        return(modules.utils.build_response_json(request.path, 200, datas))    

""" [Summary]: Validates recaptcha response from google server.
    [Returns]: Returns True captcha test passed, false otherwise.
    [TODO]: In a production environment the client and server key should be reconfigured.
"""
def is_human(captcha_response):
    # https://www.google.com/recaptcha/
    secret = RECAPTCHA_SECRET
    payload = {'response':captcha_response, 'secret':secret}
    response = requests.post("https://www.google.com/recaptcha/api/siteverify", payload)
    response_text = json.loads(response.text)
    return response_text['success']

"""
[Summary]: Check if the user has the necessary permissions to access a service.
[Returns]: True if access is granted to access the resource, false otherwise.
[ref]: CHECK THIS: https://medium.com/devgorilla/how-to-log-out-when-using-jwt-a8c7823e8a6
"""
def isAuthenticated(request):
    # 1. Check if the token is available on the request header.
    headers = dict(request.headers)
    # Debug only: print(str(len(headers)))
    
    # 2. Check if the Authorization header name was parsed.
    if 'Authorization' not in headers: raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the permission to access this resource. Please, provide an authorization token.", 403) 
    parsedToken = headers['Authorization']
    if ("Bearer" in parsedToken):
        parsedToken = (parsedToken.replace("Bearer", "")).replace(" ", "")
    
    # 3. Decode the authorization token to get the User object.
    try:
        # Decode will raise an exception if anything goes wrong within the decoding process (i.e., perform validation of the JWT).
        res_dic  = jwt.decode(parsedToken, JWT_SECRET_TOKEN, algorithms=['HS256'])
        # Get the ID of the user.
        userID = int(res_dic['id'])
        # Debug only: print(str(json.dumps(res_dic)))
       
        conn    = mysql.connect()
        cursor  = conn.cursor()
        # 3.1. Check if the token is not blacklisted, that is if a user was previously logged out from the platform but the token is still 'alive'.
        cursor.execute("SELECT ID FROM auth_token_blacklist WHERE userID=%s AND token=%s", (userID, parsedToken))
        res = cursor.fetchall()
        if (len(res) == 1):
            raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the necessary permissions to access this resource. Please, provide an authorization token.", 403) 
        cursor.close()
        cursor  = conn.cursor()

        # 3.2. Get info of the user
        # Check if this user id exists.
        cursor.execute("SELECT ID FROM user WHERE id=%s", userID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 403) 

    if (len(res) == 1): 
        cursor.close()
        conn.close()    
        return True # The user is legit, we can let him access the target resource 
    else:
        cursor.close()
        conn.close()    
        raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the necessary permissions to access this resource. Please, provide an authorization token.", 403) 

""" TODO: Merge this function with the previous one. This function is used to make sure that only admins access particular services."""
def isAuthenticatedAdmin(request):
    # 1. Check if the token is available on the request header.
    headers = dict(request.headers)
    # Debug only: print(str(len(headers)))
    
    # 2. Check if the Authorization header name was parsed.
    if 'Authorization' not in headers: raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the permission to access this resource. Please, provide an authorization token.", 403) 
    parsedToken = headers['Authorization']
    if ("Bearer" in parsedToken):
        parsedToken = (parsedToken.replace("Bearer", "")).replace(" ", "")
    
    # 3. Decode the authorization token to get the User object.
    try:
        # Decode will raise an exception if anything goes wrong within the decoding process (i.e., perform validation of the JWT).
        res_dic  = jwt.decode(parsedToken, JWT_SECRET_TOKEN, algorithms=['HS256'])
        # Get the ID of the user.
        userID = int(res_dic['id'])
        # Debug only: print(str(json.dumps(res_dic)))
        # The user is not an administrator
        if ( int(res_dic['is_admin']) == 0):
            raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the permission to access this resource.", 403) 
        
        conn    = mysql.connect()
        cursor  = conn.cursor()
        # 3.1. Check if the token is not blacklisted, that is if a user was previously logged out from the platform but the token is still 'alive'.
        cursor.execute("SELECT ID FROM auth_token_blacklist WHERE userID=%s AND token=%s", (userID, parsedToken))
        res = cursor.fetchall()
        if (len(res) == 1):
            raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the necessary permissions to access this resource. Please, provide an authorization token.", 403) 
        cursor.close()
        cursor  = conn.cursor()

        # 3.2. Get info of the user
        # Check if this user id exists.
        cursor.execute("SELECT ID FROM user WHERE id=%s", userID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 403) 

    if (len(res) == 1): 
        cursor.close()
        conn.close()    
        return True # The user is legit, we can let him access the target resource 
    else:
        cursor.close()
        conn.close()    
        raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the necessary permissions to access this resource. Please, provide an authorization token.", 403) 

Authenticate User

POST /api/user/login

Synopsis

Authenticate user with an email and password. The authentication process returns a bearer JWT used to grant users access to SAM’s Web services.

Response Headers

• Content-Type – multipart/form-data

Form Parameters

• email – The email of the user to be authenticated.

• psw – The user password.

Response JSON Object

• id (int) – The id of the user.

• email (string) – The email of the user.

• avatar (string) – Avatar of the user (i.e., location in disk).

• is_admin (boolean) – Is the user an administrator.

• exp (int) – Expiration time of the token in seconds.

• token (string) – The bearer JWT.

• status (int) – status code.

Status Codes

• 200 OK – Users successfully authenticated.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 401 Unauthorized – Fail to authenticate user / Unauthorized.

• 500 Internal Server Error – Internal server error.

Example Response

{
   "/api/user/login":{
      "id":1,
      "email":"forrest@sam.pt",
      "avatar":null,
      "is_admin":0,
      "exp":1637410963,
      "token":"eyJ0eXAiOiJKV1QiLCJhb..."
      "status":200,
   }
}

Note

By default the JSON Web Token (JWT) authentication token will expire after 15 minutes.

Logout User

POST /api/user/logout

Synopsis

Logout user with the provided authentication token that should be available in the Authorization request header.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response JSON Object

• status (int) – status code.

Status Codes

• 200 OK – User was successfully logged out.

• 500 Internal Server Error – Unable to logout user.

Example Response

{
   "/api/user/logout":{
      "status":200
   }
}

User Services API

This section includes details concerning services developed for the group entity implemented in

user.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
import json, jwt, ast
from api import app, mysql, JWT_SECRET_TOKEN, JWT_EXPIRATION_SECONDS, RECAPTCHA_SECRET
from email_validator import validate_email, EmailNotValidError
from flask import request
from datetime import datetime
import requests
from datetime import timedelta
import modules.error_handlers, modules.utils # SAM's modules

"""
[Summary]: User Authentication Service (i.e., login).
[Returns]: Returns a JSON object with the data of the user including a JWT authentication token.
"""
@app.route('/api/user/login', methods=['POST'])
def login_user():
    if request.method == "POST":
        # 1. Validate and parse POST data.
        if not request.form.get('email'):
            raise modules.error_handlers.BadRequest(request.path, 'The email cannot be empty', 400) 
        if not request.form.get('psw'):
            raise modules.error_handlers.BadRequest(request.path, 'The password cannot be empty', 400) 
        
        email   = request.form['email']
        psw     = request.form['psw']

        # 2. Connect to the DB and get the user info.
        try:
            conn    = mysql.connect()
            cursor  = conn.cursor()
            cursor.execute("SELECT ID, email, psw, avatar, administrator FROM user WHERE email=%s", email)
        except Exception as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
        # 2.1. Check if the user exists.
        if (cursor.rowcount == 0): 
            raise modules.error_handlers.BadRequest(request.path, "A user with the specified email was not found", 404) 
        
        # 2.2. Process the DB results.
        records = cursor.fetchall()
        dbpsw = ""
        data = {} # Create a new nice empty dictionary to be populated with data from the DB.
        for row in records:
            data['id']          = row[0]
            data['email']       = row[1]
            # For security reasons lets not store the password in the dic.
            dbpsw               = row[2] 
            data['avatar']      = row[3]
            data['is_admin']    = row[4]
            # Set the expiration time of the token, the JWT auth token will not be valid after x seconds
            # Default is a 15 minute session
            data['exp']     = datetime.utcnow() + timedelta(seconds=int(JWT_EXPIRATION_SECONDS))

        cursor.close()
        conn.close()    
        
        # Check if the hashed password of the database is the same as the one provided by the user.
        if modules.utils.check_password(dbpsw, psw):
            # First, build the authentication token and added it to the dictionary.
            # Second, let's create a JSON response with the data of the dictionary.
            data['token'] = (jwt.encode(data, JWT_SECRET_TOKEN, algorithm='HS256')).decode('UTF-8')
            
            # Authentication success, the user 'can follow the white rabbit'.
            return (modules.utils.build_response_json(request.path, 200, data))
        else:
            raise modules.error_handlers.BadRequest(request.path, "Authentication failure", 401)

"""
[Summary]: Clear the list of expired blacklisted JSON Web Tokens of a user.
[Arguments]:
       - $userID$: Target user.
[Returns]: Returns false, if an error occurs, true otherwise. 
"""
def clear_expired_blacklisted_JWT(userID):
    debug=False
    if (debug): print("Checking blacklisted tokens for user id ="+str(userID))
    try:
        # Check if this user id exists.
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT token FROM auth_token_blackList WHERE userID=%s", userID)
        res = cursor.fetchall()
    except Exception as e:
        if (debug): print(str(e))
        return (False) # 'Houston, we have a problem.'
    # Empty results ?
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return (True)
    else:
        i=0
        for row in res: 
            token = row[0]
            if (debug): print ("# Checking token[" + str(i) + "]" + "= " + token)
            i = i + 1
            try:
                # Let's see if the token is expired
                res_dic  = jwt.verify(token)
                if (debug): print(" - The token is still 'alive'. Nothing to do here.")
            except:
                if (debug): print(" - The token is expired, removing it from the database for user with id " + str(userID))
                # The token is expired, remove it from the DB
                try:
                    cursor.execute("DELETE FROM auth_token_blacklist WHERE token=%s AND userID=%s", (token,userID))
                    conn.commit()
                except Exception as e:
                    if (debug): print(str(e))
                    return (False) # 'Houston, we have a problem.'
    return(True)

"""
[Summary]: Performs a logout using an JWT authentication token.
[Returns]: 200 response if the user was successfully logged out.
[ref]: Based on https://medium.com/devgorilla/how-to-log-out-when-using-jwt-a8c7823e8a6
"""
@app.route('/api/user/logout', methods=['POST'])
def logout_user():
    debug = True
    
    data = {}
    if request.method != "POST": return
    # 1. Check if the token is available on the request header.
    headers = dict(request.headers)
    if (debug): print(str(len(headers)))
    
    # 2. Check if the Authorization header name was parsed.
    if 'Authorization' not in headers: raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the permission to access this resource. Please, provide an authorization token.", 403) 
    token_parsed = headers['Authorization']
    if ("Bearer" in token_parsed):
        token_parsed = (token_parsed.replace("Bearer", "")).replace(" ", "")
   
    if (debug): print("Parsed Token:" + token_parsed)
    
    try:
        # 3. From now on the token will be blacklisted because the user has logout and the token may still
        #    exists somewhere because its expiration date is still valid.
        
        # 3.1. Let's clean the house - Remove possible expired tokens from the user of the token
        res_dic  = jwt.decode(token_parsed, JWT_SECRET_TOKEN, algorithms=['HS256'])
       
        userID = int(res_dic['id'])
        if not clear_expired_blacklisted_JWT(userID): # Sanity check
            return (modules.utils.build_response_json(request.path, 500))
        # 3.2. Let's add the token to the blacklist table on the database for the current user
        #      That is, blacklist the current token, that may or may not be alive. 
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("INSERT INTO auth_token_blacklist (userID, token) VALUES (%s, %s)", (userID, token_parsed))
        conn.commit()
        data['message'] = "The authentication token was blacklisted. The user should now be logouted on the client side."
       
    except jwt.exceptions.ExpiredSignatureError as e:
        # We don't need to blacklist this token, the token is already expired (see 'exp' field of the JWT defined in the authenticate function).
        # raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
        data['message'] = "The token has already expired, no need to blacklist it. The user should now be logouted on the client side."
        return (modules.utils.build_response_json(request.path, 200, data))
    except Exception as e :
        # Double token entry ?
        if e.args[0] == 1062:
            data['message'] = "The token was already blacklisted. The user should now be logouted on the client side."
        else:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        try:
            cursor.close()
            conn.close()
        except:
            pass # cursor or conn may not be defined, I don't care, 'Just keep swimming'.
    #
    return (modules.utils.build_response_json(request.path, 200, data))

@app.route('/api/user/<email>/admin', methods=['GET'])
def is_admin(email):
    if request.method != 'GET': return
    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)

    # 2. Let's get the groups associated with the parsed user.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT email, administrator FROM user WHERE email=%s AND administrator=1", email) 
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 

    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 200, {"admin": 0})) 
    else:
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, {"admin": 1}))
"""
[Summary]: User Registration Service (i.e., add a new user).
[Returns]: Returns a JSON object with the data of the user including a JWT authentication token.
"""
@app.route('/api/user', methods=['POST'])
def add_user():
    if request.method != 'POST': return

    # 1. Let's get our shiny new JSON object and current time.
    # - Always start by validating the structure of the json, if not valid send an invalid response.
    try:
        obj = request.json
        obj=ast.literal_eval(str(obj).lower())

        date = (datetime.now()).strftime('%Y-%m-%d %H:%M:%S')
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 

    # 2. Let's validate the data of our JSON object with a custom function.
    if (not modules.utils.valid_json(obj, {"email", "psw", "firstname", "lastname", "avatar", "g-recaptcha-response"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)

    if ("insomnia" not in request.headers.get('User-Agent')):
        # 3. Validate reCAPTCHA
        if not is_human(obj['g-recaptcha-response']):
            raise modules.error_handlers.BadRequest(request.path, "reCAPTCHA failure - Bots are not allowed.", 400)

    # 4. Let's hash the hell of the password.
    hashed_psw = modules.utils.hash_password(obj['psw'])
    obj['psw'] = "" # "paranoic mode".
    
    # 5. Check if the user was not previously registered in the DB (i.e., same email)
    if (find_user(obj['email']) is not None):
        raise modules.error_handlers.BadRequest(request.path, "The user with that email already exists", 500)

    # 6. Connect to the database and create the new user.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        print(obj)
        print(hashed_psw)
        cursor.execute("INSERT INTO user (email, psw, firstName, lastName, avatar, createdon, updatedon) VALUES (%s, %s, %s, %s, %s, %s, %s)", (obj['email'], hashed_psw, obj['firstname'], obj['lastname'], obj['avatar'], date, date))
        conn.commit()
    except Exception as e:
        print("--->" +str(e))
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 7. Authentication success, the user can now choose to 'take the red or blue pill to follow the white rabbit'
    return (modules.utils.build_response_json(request.path, 200))

"""
[Summary]: Get users.
[Returns]: Returns a User object.
"""
# Check if a user exists
@app.route('/api/users', methods=['GET'])
def get_users():
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)
    
    # 3. Let's get users from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, email, firstName, lastName, avatar, userStatus, administrator, createdon, updatedon FROM user")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Empty results ?
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] 
        for row in res:
            data = {}
            data['id']          = row[0]
            data['email']       = row[1]
            data['firstName']   = row[2]
            data['lastName']    = row[3]
            data['avatar']      = row[4]
            data['user_status']  = row[5]
            data['administrator'] = row[6]
            data['createdon']   = row[7]
            data['updatedon']   = row[8]
            datas.append(data)
        cursor.close()
        conn.close()
        # 4. Return information about the user (except the password) and 'May the Force be with you'.
        return(modules.utils.build_response_json(request.path, 200, datas))    

"""
[Summary]: Finds a user by email.
[Returns]: Returns a User object.
"""
# Check if a user exists
@app.route('/api/user/<email>', methods=['GET'])
def find_user(email, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    if (not internal_call):
        isAuthenticated(request)
       
    # 2. Let's validate the email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(email)
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 
    
    # 3. Let's get the user from the database with the provided [email].
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, email, firstName, lastName, avatar FROM user WHERE email=%s", email)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Empty results ?
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        data = {} # Create a new nice empty dictionary to be populated with data from the DB.
        for row in res:
            data['id']          = row[0]
            data['email']       = row[1]
            data['firstName']   = row[2]
            data['lastName']    = row[3]
            data['avatar']      = row[4]
        cursor.close()
        conn.close()

        # 4. Return information about the user (except the password) and 'May the Force be with you'.
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, data))
        else:
            return(data)

"""
[Summary]: Delete a user
[Returns]: Returns a success or error response
"""
@app.route('/api/user/<email>', methods=["DELETE"])
def delete_user(email):
    if request.method != 'DELETE': return
    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)
  
    # 2. Let's validate the email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(email)
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 

    # 3. Connect to the database and delete the user
    # TODO: Let's build procedures in the DB to delete Users. 
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM user WHERE email=%s", email)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 4. The Delete request was a success, the user 'took the blue pill'.
    return (modules.utils.build_response_json(request.path, 200))

"""
[Summary]: Updates a user
[Returns]: Returns a success or error response
"""
@app.route('/api/user/<email>', methods=["PUT"])
def update_user(email):
    updatePsw = False
    # Note: Remember that if an email is being changed, the email argument is the old one; 
    #       The new email content is available on the JSON object parsed in the body of the request.  
    if request.method != 'PUT': return
    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)

    # 2. Let's validate the email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(email)
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 

    # 3. Let's get our shiny new JSON object and current time.
    # - Always start by validating the structure of the json, if not valid send an invalid response.
    try:
        obj = request.json
        date = (datetime.now()).strftime('%Y-%m-%d %H:%M:%S')
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 


    # 4. Let's validate the data of our JSON object with a custom function.
    if (not modules.utils.valid_json(obj, {"email", "avatar", "firstname", "lastname"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)

    # 4.1. Let's also validate the new email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(obj['email'])
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 

    # 5. Hash the new password and store it (if supplied)
    if (modules.utils.valid_json(obj, {"psw"})):
        updatePsw=True
        hashed_psw = modules.utils.hash_password(obj['psw'])
        obj['psw'] = "" # "paranoic mode".

    # 6. Connect to the database and update the user with the data of the parsed json object
    # TODO: - Let's build procedures in the DB to update Users. 
    #       - Let's not update every single field of the User, instead, let's just updated the one that has changed.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        if (updatePsw):
            cursor.execute("UPDATE user SET email=%s, psw=%s, firstName=%s, lastName=%s, avatar=%s, updatedOn=%s WHERE email=%s",  (obj['email'], hashed_psw, obj['firstname'], obj['lastname'], obj['avatar'],date,email))
        else:
            cursor.execute("UPDATE user SET email=%s, firstName=%s, lastName=%s, avatar=%s, updatedOn=%s WHERE email=%s",  (obj['email'], obj['firstname'], obj['lastname'], obj['avatar'],date,email))    
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 4. The Update request was a success, the user 'is in the rabbit hole'
    return (modules.utils.build_response_json(request.path, 200))

"""
[Summary]: Finds groups of a user.
[Returns]: Returns a success or error response
"""
@app.route('/api/user/<email>/groups', methods=["GET"])
def find_user_groups(email):
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    isAuthenticated(request)
       
    # 2. Let's validate the email, invalid emails from this point are not allowed.
    try:
        valid = validate_email(email)
    except EmailNotValidError as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 
    
    # 3. Let's get the user from the database with the provided [email].
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT user_id, user_email, user_group FROM view_user_group WHERE user_email=%s", email)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Empty results ?
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = []
        for row in res:
            data = {} # Create a new nice empty dictionary to be populated with data from the DB.
            data['user_id']     = row[0]
            data['user_email']  = row[1]
            data['user_group']  = row[2]
            datas.append(data)
        cursor.close()
        conn.close()
        # 4. Return information about the user (except the password) and 'May the Force be with you'.
        return(modules.utils.build_response_json(request.path, 200, datas))    

""" [Summary]: Validates recaptcha response from google server.
    [Returns]: Returns True captcha test passed, false otherwise.
    [TODO]: In a production environment the client and server key should be reconfigured.
"""
def is_human(captcha_response):
    # https://www.google.com/recaptcha/
    secret = RECAPTCHA_SECRET
    payload = {'response':captcha_response, 'secret':secret}
    response = requests.post("https://www.google.com/recaptcha/api/siteverify", payload)
    response_text = json.loads(response.text)
    return response_text['success']

"""
[Summary]: Check if the user has the necessary permissions to access a service.
[Returns]: True if access is granted to access the resource, false otherwise.
[ref]: CHECK THIS: https://medium.com/devgorilla/how-to-log-out-when-using-jwt-a8c7823e8a6
"""
def isAuthenticated(request):
    # 1. Check if the token is available on the request header.
    headers = dict(request.headers)
    # Debug only: print(str(len(headers)))
    
    # 2. Check if the Authorization header name was parsed.
    if 'Authorization' not in headers: raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the permission to access this resource. Please, provide an authorization token.", 403) 
    parsedToken = headers['Authorization']
    if ("Bearer" in parsedToken):
        parsedToken = (parsedToken.replace("Bearer", "")).replace(" ", "")
    
    # 3. Decode the authorization token to get the User object.
    try:
        # Decode will raise an exception if anything goes wrong within the decoding process (i.e., perform validation of the JWT).
        res_dic  = jwt.decode(parsedToken, JWT_SECRET_TOKEN, algorithms=['HS256'])
        # Get the ID of the user.
        userID = int(res_dic['id'])
        # Debug only: print(str(json.dumps(res_dic)))
       
        conn    = mysql.connect()
        cursor  = conn.cursor()
        # 3.1. Check if the token is not blacklisted, that is if a user was previously logged out from the platform but the token is still 'alive'.
        cursor.execute("SELECT ID FROM auth_token_blacklist WHERE userID=%s AND token=%s", (userID, parsedToken))
        res = cursor.fetchall()
        if (len(res) == 1):
            raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the necessary permissions to access this resource. Please, provide an authorization token.", 403) 
        cursor.close()
        cursor  = conn.cursor()

        # 3.2. Get info of the user
        # Check if this user id exists.
        cursor.execute("SELECT ID FROM user WHERE id=%s", userID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 403) 

    if (len(res) == 1): 
        cursor.close()
        conn.close()    
        return True # The user is legit, we can let him access the target resource 
    else:
        cursor.close()
        conn.close()    
        raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the necessary permissions to access this resource. Please, provide an authorization token.", 403) 

""" TODO: Merge this function with the previous one. This function is used to make sure that only admins access particular services."""
def isAuthenticatedAdmin(request):
    # 1. Check if the token is available on the request header.
    headers = dict(request.headers)
    # Debug only: print(str(len(headers)))
    
    # 2. Check if the Authorization header name was parsed.
    if 'Authorization' not in headers: raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the permission to access this resource. Please, provide an authorization token.", 403) 
    parsedToken = headers['Authorization']
    if ("Bearer" in parsedToken):
        parsedToken = (parsedToken.replace("Bearer", "")).replace(" ", "")
    
    # 3. Decode the authorization token to get the User object.
    try:
        # Decode will raise an exception if anything goes wrong within the decoding process (i.e., perform validation of the JWT).
        res_dic  = jwt.decode(parsedToken, JWT_SECRET_TOKEN, algorithms=['HS256'])
        # Get the ID of the user.
        userID = int(res_dic['id'])
        # Debug only: print(str(json.dumps(res_dic)))
        # The user is not an administrator
        if ( int(res_dic['is_admin']) == 0):
            raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the permission to access this resource.", 403) 
        
        conn    = mysql.connect()
        cursor  = conn.cursor()
        # 3.1. Check if the token is not blacklisted, that is if a user was previously logged out from the platform but the token is still 'alive'.
        cursor.execute("SELECT ID FROM auth_token_blacklist WHERE userID=%s AND token=%s", (userID, parsedToken))
        res = cursor.fetchall()
        if (len(res) == 1):
            raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the necessary permissions to access this resource. Please, provide an authorization token.", 403) 
        cursor.close()
        cursor  = conn.cursor()

        # 3.2. Get info of the user
        # Check if this user id exists.
        cursor.execute("SELECT ID FROM user WHERE id=%s", userID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 403) 

    if (len(res) == 1): 
        cursor.close()
        conn.close()    
        return True # The user is legit, we can let him access the target resource 
    else:
        cursor.close()
        conn.close()    
        raise modules.error_handlers.BadRequest(request.path, "Authentication failure - You don't have the necessary permissions to access this resource. Please, provide an authorization token.", 403) 

Get Users

GET /api/user

Synopsis

Get all users

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Id of the user.

• email (string) – email of the user.

• avatar (string) – avatar of the user (i.e., location in disk).

• firstname (string) – First name of the user.

• lastname (string) – Last name of the user.

• user_status (boolean) – Is the user active.

• administrator (boolean) – Is the user an admin.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – status code.

Status Codes

• 200 OK – Users successfully retrieved.

• 500 Internal Server Error – Fail to retrieve users.

Example Response

{
   "/api/users":{
      "content":[
         {
            "administrator":1,
            "avatar":null,
            "createdon":"Thu, 18 Nov 2021 12:38:43 GMT",
            "email":"admin@sam.pt",
            "firstName":"Administrator",
            "id":1,
            "lastName":null,
            "updatedon":"Thu, 18 Nov 2021 12:38:43 GMT",
            "user_status":1
         },
         {
            "administrator":0,
            "avatar":null,
            "createdon":"Thu, 18 Nov 2021 12:38:43 GMT",
            "email":"forrest@sam.pt",
            "firstName":"Forrest",
            "id":2,
            "lastName":"Gump",
            "updatedon":"Thu, 18 Nov 2021 12:38:43 GMT",
            "user_status":1
         }
      ],
      "status":200
   }
}

---

GET /api/user/(string: email)

Synopsis

Get a user by email.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• email – The email of the user to be retrieved.

Response JSON Object

• id (int) – Id of the user.

• email (string) – email of the user.

• avatar (string) – avatar of the user (i.e., location in disk).

• firstname (string) – First name of the user.

• lastname (string) – Last name of the user.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – status code.

Status Codes

• 200 OK – User successfully retrieved.

• 500 Internal Server Error – Fail to retrieve user.

Example Response

{
   "/api/user/forrest@sam.pt":{
      "avatar":null,
      "email":"forrest@sam.pt",
      "firstName":"Forrest",
      "id":2,
      "lastName":"Gump",
      "status":200
   }
}

Get User Groups

GET /api/user/(string: email)/groups

Synopsis

Get the list of groups mapped to a user identified by email.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• email – The email of the user.

Response JSON Object

• user_id (int) – Id of the user.

• user_email (string) – email of the user.

• user_group (string) – Group of the user.

• status (int) – status code.

Status Codes

• 200 OK – User groups successfully retrieved.

• 500 Internal Server Error – Fail to retrieve user groups.

Example Response

{
   "/api/user/admin@SAM.pt/groups":{
      "content":[
         {
            "user_email":"admin@sam.pt",
            "user_group":"Administrators",
            "user_id":1
         },
         {
            "user_email":"admin@sam.pt",
            "user_group":"Users",
            "user_id":1
         }
      ],
      "status":200
   }
}

Check if User is an Admin

GET /api/user/(string: email)/admin

Synopsis

Check if the user identified by email is an administrator.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• email – The email of the user to be checked.

Response JSON Object

• admin (boolean) – Is the user an admin.

• status (int) – status code.

Status Codes

• 200 OK – Check performed to see if the user is an administrator.

• 500 Internal Server Error – Fail to verify user group.

Example Response

{
   "/api/user/admin@sam.pt/admin":{
      "admin":1,
      "status":200
   }
}

Add User

POST /api/user

Synopsis

Add a new user.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• email (string) – User email.

• psw (string) – User password.

• firstname (string) – User first name.

• lastname (string) – User last name.

• avatar (string) – avatar of the user (i.e., location in disk).

• g-recaptcha-response (Object) – Google ReCaptcha response object.

Response JSON Object

• status (int) – status code.

Status Codes

• 200 OK – New user added.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to add user.

Important

On a production environment, please, do not post the password without SSL enabled.

Example Request

{
   "email":"new_user@user.com",
   "psw":"123",
   "firstname":"First Name",
   "lastname":"Last Name",
   "avatar":"new_user.png",
   "g-recaptcha-response": null
}

Note

The g-recaptcha-response should not be null, a Google ReCaptcha response should be included in the JSON request object.

Example Response

{
   "/api/user":{
      "status":200
   }
}

Update User

PUT /api/user/(string: email)

Synopsis

Updates a user by email

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• email – The email of the user to be updated.

Request JSON Object

• email (string) – User email.

• psw (string) – User password.

• firstname (string) – User first name.

• lastname (string) – User last name.

• avatar (string) – avatar of the user (i.e., location in disk).

Response JSON Object

• status (int) – status code.

Status Codes

• 200 OK – User updated.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to update user.

Important

On a production environment, please, do not post the password without SSL enabled.

Example Request

{
   "email":"new_user_updated@user.com",
   "firstname":"First Name Updated",
   "lastname":"Last Name Updated",
   "psw":"1234",
   "avatar":"new_user_updated.png",
}

Example Response

{
   "/api/user":{
      "status":200
   }
}

Remove User

DELETE /api/user/(string: email)

Synopsis

Removes a user by email

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• email – The email of the user to be removed.

Response JSON Object

• status (int) – status code.

Status Codes

• 200 OK – User successfully removed.

• 500 Internal Server Error – Fail to remove user.

Example Response

{
   "/api/user/new_user@user.com":{
      "status":200
   }
}

Group Services API

This section includes details concerning services developed for the group entity implemented in

group.py

""""""
"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
from api import app, mysql
from flask import request
import modules.error_handlers, modules.utils # SAM's modules
import views.user, views.answer # SAM's views

"""
[Summary]: Adds a new question to the database.
[Returns]: Response result.
"""
@app.route('/api/group', methods=['POST'])
def add_group():
    DEBUG=True
    if request.method != 'POST': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"designation"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)   

    designation = json_data['designation']
    g_modules   = "modules" in json_data and json_data['modules'] or None
    g_users     = "users" in json_data and json_data['users'] or None
    createdon   = "createdon" in json_data and json_data['createdon'] or None
    updatedon   = "updatedon" in json_data and json_data['updatedon'] or None
    
    # Build the SQL instruction using our handy function to build sql instructions.
    values = (designation, createdon, updatedon)
    sql, values = modules.utils.build_sql_instruction("INSERT INTO sam.group", ["designation", createdon and "createdon" or None, updatedon and "updatedon" or None], values)
    if (DEBUG): print("[SAM-API]: [POST]/api/group - " + sql)

    print(g_modules)
    print(g_users)
    
    # Add
    n_id = modules.utils.db_execute_update_insert(mysql, sql, values)
    if (n_id is None):
        return(modules.utils.build_response_json(request.path, 400))  
    else:
        # If any, link the list of provided users or modules to this group
        if (g_users):
            for g_user in g_users:
                values = (g_user['id'], n_id)
                sql, values = modules.utils.build_sql_instruction("INSERT INTO user_group", ["userID", "groupID"], values)
                modules.utils.db_execute_update_insert(mysql, sql, values)
        if (g_modules):
            for g_module in g_modules:
                values = (g_module['id'], n_id)
                sql, values = modules.utils.build_sql_instruction("INSERT INTO module_group", ["moduleID", "groupID"], values)
                modules.utils.db_execute_update_insert(mysql, sql, values)
        
        return(modules.utils.build_response_json(request.path, 200, {"id": n_id}))  

"""
[Summary]: Updates a group.
[Returns]: Response result.
"""
@app.route('/api/group', methods=['PUT'])
def update_group():
    DEBUG=True
    if request.method != 'PUT': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"id"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    

    group_id    = json_data['id']
    designation = "designation" in json_data and json_data['designation'] or None
    g_modules   = "modules" in json_data and json_data['modules'] or None
    g_users     = "users" in json_data and json_data['users'] or None
    createdon   = "createdon"   in json_data and json_data['createdon'] or None
    updatedon   = "updatedon"   in json_data and json_data['updatedon'] or None

    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Build the SQL instruction using our handy function to build sql instructions.
    values  = (designation, createdon, updatedon)
    columns = [designation and "designation" or None, createdon and "createdon" or None, updatedon and "updatedOn" or None]
    where   = "WHERE id="+str(group_id)
    # Check if there is anything to update (i.e. frontend developer has not sent any values to update).
    if (len(values) == 0): return(modules.utils.build_response_json(request.path, 200))   

    sql, values = modules.utils.build_sql_instruction("UPDATE sam.group", columns, values, where)
    if (DEBUG): print("[SAM-API]: [PUT]/api/group - " + sql + " " + str(values))

    # Update Recommendation
    modules.utils.db_execute_update_insert(mysql, sql, values)
    
    # Check if there are any user flagged to be removed, what is removed is not the user but the mapping of a user to the current group.
    if g_users:
        for g_user in g_users:
            flag_remove = "to_remove" in g_user and g_user['to_remove'] or None
            # Remove the link between the user and the group
            if (flag_remove):
                try:
                    conn    = mysql.connect()
                    cursor  = conn.cursor()
                    cursor.execute("DELETE FROM user_group WHERE userID=%s", g_user['id'])
                    conn.commit()
                except Exception as e:
                    print("entrou")
                    raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
                finally:
                    cursor.close()
                    conn.close()
            # Add a new user mapping
            else:
                values = (g_user['id'], group_id)
                sql, values = modules.utils.build_sql_instruction("INSERT INTO user_group", ["userID", "groupID"], values)
                modules.utils.db_execute_update_insert(mysql, sql, values)
    
    # Do as above, but for modules.
    if g_modules:
        for g_module in g_modules:
            flag_remove = "to_remove" in g_module and g_module['to_remove'] or None
            # Remove the link between the user and the group
            if (flag_remove):
                try:
                    conn    = mysql.connect()
                    cursor  = conn.cursor()
                    cursor.execute("DELETE FROM module_group WHERE moduleID=%s", g_module['id'])
                    conn.commit()
                except Exception as e:
                    raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
                finally:
                    cursor.close()
                    conn.close()
            # Add a new module mapping
            else:
                values = (g_module['id'], group_id)
                sql, values = modules.utils.build_sql_instruction("INSERT INTO module_group", ["moduleID", "groupID"], values)
                modules.utils.db_execute_update_insert(mysql, sql, values)

    return(modules.utils.build_response_json(request.path, 200))   

"""
[Summary]: Get Groups.
[Returns]: Response result.
"""
@app.route('/api/groups')
def get_groups():
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, designation, createdon, updatedon FROM sam.group")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['designation'] = row[1]
            data['modules']     = find_modules_of_group(row[0])
            data['users']       = find_users_of_group(row[0])
            data['createdon']   = row[2]
            data['updatedon']   = row[3]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas)) 

"""
[Summary]: Finds the list of modules linked to a type.
[Returns]: A list of modules or an empty array if None are found.
"""
def find_modules_of_group(group_id):
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT moduleID FROM module_group WHERE groupID=%s", group_id)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return([]) 
    else:
        modules = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            module = views.module.find_module(row[0], True)[0]
            del module['tree']
            del module['dependencies']
            del module['recommendations']
            modules.append(module)
        cursor.close()
        conn.close()
       
        # 'May the Force be with you, young master'.
        return(modules)

def find_users_of_group(group_id):
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT user_email FROM view_user_group WHERE group_id=%s", group_id)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return([]) 
    else:
        users = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            user = views.user.find_user(row[0], True)
            users.append(user)
        cursor.close()
        conn.close()
       
        # 'May the Force be with you, young master'.
        return(users)

"""
[Summary]: Finds Question.
[Returns]: Response result.
"""
@app.route('/api/group/<ID>', methods=['GET'])
def find_group(ID):
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT id, designation, createdon, updatedon FROM sam.group WHERE id=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['designation'] = row[1]
            data['modules']     = find_modules_of_group(row[0])
            data['users']       = find_users_of_group(row[0])
            data['createdon']   = row[2]
            data['updatedon']   = row[3]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas)) 

"""
[Summary]: Delete a Group.
[Returns]: Returns a success or error response
"""
@app.route('/api/group/<ID>', methods=["DELETE"])
def delete_group(ID):
    if request.method != 'DELETE': return
    # 1. Check if the user has permissions to access this resource.
    views.user.isAuthenticated(request)

    # 2. Connect to the database and delete the resource.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM sam.group WHERE ID=%s", ID)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 3. The Delete request was a success, the user 'took the blue pill'.
    return (modules.utils.build_response_json(request.path, 200))

Get Groups

GET /api/group

Synopsis

Get all groups.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Id of the group.

• designation (string) – Description of the group.

• modules (array) – Array of modules mapped to the group.

• users (array) – Array of users.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – status code.

Status Codes

• 200 OK – Groups successfully retrieved.

• 500 Internal Server Error – Fail to retrieve groups.

Example Response

{
   "/api/groups":{
      "content":[
         {
            "createdon":"Thu, 18 Nov 2021 12:38:43 GMT",
            "designation":"Administrators",
            "id":1,
            "modules":[],
            "updatedon":"Thu, 18 Nov 2021 12:38:43 GMT",
            "users":[
               {
                  "avatar":null,
                  "email":"admin@sam.pt",
                  "firstName":"Administrator",
                  "id":1,
                  "lastName":null
               }
            ]
         }
      ],
      "status":200
   }
}

---

GET /api/group/(int: id)

Synopsis

Get a group by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id – The id of the group to be retrieved.

Response JSON Object

• id (int) – Id of the group.

• designation (string) – Description of the group.

• modules (array) – Array of modules mapped to the group.

• users (array) – Array of users.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – status code.

Status Codes

• 200 OK – Groups successfully retrieved.

• 500 Internal Server Error – Fail to retrieve groups.

Example Response

{
   "/api/groups":{
      "content":[
         {
            "createdon":"Thu, 18 Nov 2021 12:38:43 GMT",
            "designation":"Administrators",
            "id":1,
            "modules":[],
            "updatedon":"Thu, 18 Nov 2021 12:38:43 GMT",
            "users":[
               {
                  "avatar":null,
                  "email":"admin@sam.pt",
                  "firstName":"Administrator",
                  "id":1,
                  "lastName":null
               }
            ]
         }
      ],
      "status":200
   }
}

Add Group

POST /api/group

Synopsis

Adds a new group.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• designation (string) – The name of the group.

• users (array) – The id of each user that will belong to the new group.

• modules (array) – The id of each module that will belong to the new group.

Response JSON Object

• id (int) – Id assigned to the new group.

• status (int) – status code.

Status Codes

• 200 OK – New group added with id (see example response).

• 500 Internal Server Error – Fail to add a new group.

Example Request

{"designation":"New Group","users":[{"id":1}],"modules":[{"id":1}]}

Example Response

{"/api/group":{"id":3,"status":200}}

Edit Group

PUT /api/group

Synopsis

Updates the information of a group.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• id (int) – The id of the group you want to update.

• designation (string) – The new name of the group.

Response JSON Object

• status (int) – status code.

Status Codes

• 200 OK – Group successfully updated.

• 500 Internal Server Error – Fail to update group.

Example Request

{"id":3,"designation":"New Group Updated"}

Example Response

{"/api/group":{"status":200}}

Remove Group

DELETE /api/group/(int: id)

Synopsis

Remove a group by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id – The id of the group to be removed.

Response JSON Object

• status (int) – status code.

Status Codes

• 200 OK – Group successfully removed.

• 500 Internal Server Error – Fail to remove group.

Example Response

{"/api/group/3":{"status":200}}

File Services API

This section includes details concerning services developed for the file entity implemented in

file.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
from api import app
from flask import request, abort, jsonify, send_from_directory
import os, views.user, modules.utils
from werkzeug.utils import secure_filename

UPLOAD_DIRECTORY="./external/"

@app.route("/api/file/<path:path>", methods=['GET'])
def get_file(path):
    if request.method != 'GET': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)
    
    return send_from_directory(UPLOAD_DIRECTORY, path, as_attachment=True)

@app.route("/api/files", methods=['GET'])
def list_files():
    if request.method != 'GET': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    files = []
    for filename in os.listdir(UPLOAD_DIRECTORY):
        path = os.path.join(UPLOAD_DIRECTORY, filename)
        if os.path.isfile(path):
            files.append(filename)
    return jsonify(files)

@app.route("/api/file/<filename>", methods=["POST"])
def post_file(filename):
    if request.method != 'POST': return
    file = request.files['file']
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    if "/" in filename:
        # Return 400 BAD REQUEST
        abort(400, "no subdirectories directories allowed")

    if file:
        filename = secure_filename(filename)
        file.save(UPLOAD_DIRECTORY + filename)

    # Return 201 CREATED
    return(modules.utils.build_response_json(request.path, 201))

@app.route('/api/file/module/<module_name>/session/<ID>', methods=['GET'])
def download_recommendations_zip(module_name, ID):
    if request.method != 'GET': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)
    
    file_name = str(module_name)+'_session_'+str(ID)+'.zip'
    return send_from_directory('./temp/', file_name, as_attachment=True)

Upload File

POST /api/file/(string: filename)

Synopsis

Uploads a file to the predefined UPLOAD_DIRECTORY.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – multipart/form-data

Parameters

• filename – The name of the file.

Form Parameters

• file – The file to be uploaded.

Response JSON Object

• status (int) – status code.

Status Codes

• 201 Created – The file was successfully uploaded.

• 400 Bad Request – Fail to upload file.

Example Response

{
   "/api/file/example.md":{
      "status":201
   }
}

Request File

GET /api/file/(string: filename)

Synopsis

Returns a file from the predefined UPLOAD_DIRECTORY.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• filename – The name of the file.

Status Codes

• 201 Created – The file was successfully uploaded.

• 400 Bad Request – Fail to upload file.

Get Files

GET /api/file/(string: filename)

Synopsis

Returns the list of files available on the predefined UPLOAD_DIRECTORY.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• filename – The name of the file.

Status Codes

• 200 OK – The list of files was successfully retrieved.

Example Response

["example.md","example_2.md"]

Get Session Files

GET /api/file/module/(string: shortname)/session/(int: id)

Synopsis

Returns a zip containing all recommendations for a specific session id and module identified by shortname.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• shortname – The short name of the module.

• id – The id of the session.

Status Codes

• 200 OK – The zip file was successfully created.

Types Services API

This section includes details concerning services developed for the type entity implemented in

type.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
from api import app, mysql
from flask import request
import modules.error_handlers, modules.utils # SAM's modules
import views.user # SAM's views

"""
[Summary]: Adds a new type to the database.
[Returns]: Response result.
"""
@app.route('/api/type', methods=['POST'])
def add_type():
    DEBUG=True
    if request.method != 'POST': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"name"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    

    name        = json_data['name']
    description = "description" in json_data and json_data['description'] or None
    createdon   = "createdon" in json_data and json_data['createdon'] or None
    updatedon   = "updatedon" in json_data and json_data['updatedon'] or None
    
    # Build the SQL instruction using our handy function to build sql instructions.
    values = (name, description, createdon, updatedon)
    sql, values = modules.utils.build_sql_instruction("INSERT INTO type", ["name", description and "description" or None, createdon and "createdon" or None, updatedon and "updatedon" or None], values)
    if (DEBUG): print("[SAM-API]: [POST]/api/type - " + sql)

    # Add
    n_id = modules.utils.db_execute_update_insert(mysql, sql, values)
    if (n_id is None):
        return(modules.utils.build_response_json(request.path, 400))  
    else:
        return(modules.utils.build_response_json(request.path, 200, {"id": n_id}))

"""
[Summary]: Updates a type.
[Returns]: Response result.
"""
@app.route('/api/type', methods=['PUT'])
def update_type():
    DEBUG=True
    if request.method != 'PUT': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"id"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    

    name        = "name"        in json_data and json_data['name'] or None
    description = "description" in json_data and json_data['description'] or None
    createdon   = "createdon"   in json_data and json_data['createdon'] or None
    updatedon   = "updatedon"   in json_data and json_data['updatedon'] or None

    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Build the SQL instruction using our handy function to build sql instructions.
    values  = (name, description, createdon, updatedon)
    columns = [name and "name" or None, description and "description" or None, createdon and "createdon" or None, updatedon and "updatedOn" or None]
    where   = "WHERE id="+str(json_data['id'])
    # Check if there is anything to update (i.e. frontend developer has not sent any values to update).
    if (len(values) == 0): return(modules.utils.build_response_json(request.path, 200))   

    sql, values = modules.utils.build_sql_instruction("UPDATE type", columns, values, where)
    if (DEBUG): print("[SAM-API]: [PUT]/api/type - " + sql + " " + str(values))

    # Update Recommendation
    modules.utils.db_execute_update_insert(mysql, sql, values)

    return(modules.utils.build_response_json(request.path, 200))   

"""
[Summary]: Get Questions.
[Returns]: Response result.
"""
@app.route('/api/types')
def get_types():
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, name, description, createdOn, updatedOn FROM type")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['name']        = row[1]
            data['description'] = row[2]
            data['modules']     = find_modules_of_type(row[0])
            data['createdon']   = row[3]
            data['updatedon']   = row[4]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas)) 

"""
[Summary]: Finds the list of modules linked to a type.
[Returns]: A list of modules or an empty array if None are found.
"""
def find_modules_of_type(type_id):
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID FROM module WHERE typeID=%s", type_id)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return([]) 
    else:
        modules = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            module = views.module.find_module(row[0], True)[0]
            del module['tree']
            del module['dependencies']
            del module['recommendations']
            modules.append(module)
        cursor.close()
        conn.close()
       
        # 'May the Force be with you, young master'.
        return(modules)

"""
[Summary]: Finds a Type.
[Returns]: Response result.
"""
@app.route('/api/type/<ID>', methods=['GET'])
def find_type(ID):
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, name, description, createdOn, updatedOn FROM type WHERE ID=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['name']        = row[1]
            data['description'] = row[2]
            data['createdon']   = row[3]
            data['updatedon']   = row[4]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas)) 

"""
[Summary]: Delete a type.
[Returns]: Returns a success or error response
"""
@app.route('/api/type/<ID>', methods=["DELETE"])
def delete_type(ID):
    if request.method != 'DELETE': return
    # 1. Check if the user has permissions to access this resource.
    views.user.isAuthenticated(request)

    # 2. Connect to the database and delete the resource.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM type WHERE ID=%s", ID)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 3. The Delete request was a success, the user 'took the blue pill'.
    return (modules.utils.build_response_json(request.path, 200))

Get Types

GET /api/types

Synopsis

Get types.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Id of the type.

• name (string) – Name of the type.

• description (string) – Description of the type.

• modules (array) – Array of modules mapped to the current type.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – status code.

Status Codes

• 200 OK – Types successfully retrieved.

• 500 Internal Server Error – Fail to retrieve types.

Example Response

{
   "/api/types":{
      "content":[
         {
            "id":1,
            "name":"Test Type",
            "description":"Test Type Description",
            "modules":[],
            "createdon":"Mon, 20 Sep 2021 09:00:00 GMT",
            "updatedon":"Mon, 20 Sep 2021 09:00:00 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/type/(int: id)

Synopsis

Get a type identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – id of the type.

Response JSON Object

• id (int) – Id of the type.

• name (string) – Name of the type.

• description (string) – Description of the type.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – status code.

Status Codes

• 200 OK – Type successfully retrieved.

• 500 Internal Server Error – Fail to retrieve type.

Example Response

{
   "/api/type/1":{
      "content":[
         {
            "id":1,
            "name":"Test Type",
            "description":"Test Type Description",
            "createdon":"Mon, 20 Sep 2021 09:00:00 GMT",
            "updatedon":"Mon, 20 Sep 2021 09:00:00 GMT"
         }
      ],
      "status":200
   }
}

Add Type

POST /api/type

Synopsis

Add a new type.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• name (string) – Name of the type.

• description (string) – Description of the type.

Response JSON Object

• status (int) – status code.

Status Codes

• 200 OK – Type successfully added.

• 500 Internal Server Error – Fail to add type.

Example Request

{
   "name":"Test Type",
   "description":"Test Type Description"
}

Example Response

{"/api/type":{"status":200}}

Edit Type

PUT /api/type

Synopsis

Update a type.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• id (int) – Id of the module to update.

• name (string) – Name of the type.

• description (string) – Description of the type.

Response JSON Object

• status (int) – status code.

Status Codes

• 200 OK – Type successfully updated.

• 500 Internal Server Error – Fail to update type.

Example Request

{
   "id":1,
   "name":"Test Type Updated",
   "description":"Test Type Updated"
}

Example Response

{"/api/type":{"status":200}}

Remove Type

DELETE /api/type/(int: id)

Synopsis

Remove a type identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id – The id of the type to be removed.

Response JSON Object

• status (int) – status code.

Status Codes

• 200 OK – Type successfully removed.

• 500 Internal Server Error – Fail to remove type.

Example Response

{"/api/type/1":{"status":200}}

Module Services API

This section includes details concerning services developed for the module entity implemented in

module.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
from api import app, mysql
from flask import request
from datetime import datetime
import os
import modules.error_handlers, modules.utils # SAM's modules
import views.user, views.recommendation, views.question, views.dependency # SAM's views

"""
[Summary]: Adds a new Module.
[Returns]: Response result.
"""
@app.route('/api/module', methods=['POST'])
def add_module():
    DEBUG=False
    if request.method != 'POST': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticatedAdmin(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON
    if (not modules.utils.valid_json(json_data, {"shortname", "fullname", "displayname"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    
    
    shortname       = json_data['shortname']
    fullname        = json_data['fullname']
    displayname     = json_data['displayname']

    # Check if module's short name and display name are unique
    shortnames, displaynames = get_modules_short_displaynames()
    if shortname in shortnames:
        raise modules.error_handlers.BadRequest(request.path, str("'Abbreviation' already in use."), 500) 
    if displayname in displaynames:
        raise modules.error_handlers.BadRequest(request.path, str("'Display Name' already in use."), 500) 

    tree            = None
    if ('tree' in json_data): 
        tree = json_data['tree']
    recommendations = "recommendations" in json_data and json_data['recommendations'] or None
    dependencies    = "dependencies" in json_data and json_data['dependencies'] or None
    avatar      = "avatar" in json_data and json_data['avatar'] or None
    description = "description" in json_data and json_data['description'] or None
    type_id     = "type_id" in json_data and json_data['type_id'] or None
    logic       = "logic_filename" in json_data and json_data['logic_filename'] or None
    createdon   = "createdon" in json_data and json_data['createdon'] or None
    updatedon   = "updatedon" in json_data and json_data['updatedon'] or None
    
    # Build the SQL instruction using our handy function to build sql instructions.
    columns = ["shortname", "fullname", "displayname", type_id and "typeID" or None, avatar and "avatar" or None, description and "description" or None, createdon and "createdon" or None, updatedon and "updatedon" or None]
    values  = (shortname, fullname, displayname, type_id, avatar, description, createdon, updatedon)
    
    sql, values = modules.utils.build_sql_instruction("INSERT INTO module", columns, values)
    if (DEBUG): print("[SAM-API]: [POST]/api/module - " + sql + " => " + str(values))

    # Add Module and iterate the tree of the module in order to create the questions and answers mapped to the current module.
    module_id = modules.utils.db_execute_update_insert(mysql, sql, values)
    if ('tree' in json_data):
        for node in tree: 
            iterate_tree_nodes(recommendations, "INSERT", module_id, node)
    
    # Store the mapping of question_answer and recommendations (DB table Recommendation_Question_Answer)
    # Get the question_answer id primary key value, through [question_id] and [answer_id]
    if recommendations:
        for recommendation in recommendations:
            for question_answer in recommendation['questions_answers']:
                qa_res = views.question.find_question_answers_2(question_answer['question_id'], question_answer['answer_id'], True)
                if (qa_res is None): return(modules.utils.build_response_json(request.path, 400)) 
                qa_res = qa_res[0]
                if (DEBUG): print("[SAM-API] [POST]/api/module - question_id = " + str(question_answer['question_id']) + ", answer_id=" + str(question_answer['answer_id']) + " => Question_Answer_id =" + str(qa_res['question_answer_id']))
                question_answer['id'] = qa_res['question_answer_id']
    
        # Add the recommendation with the link between questions and answers
        for recommendation in recommendations:
            views.recommendation.add_recommendation(recommendation)
    
    # Add dependencies, only if the current module depends on another module.
    if (module_id and dependencies):
        for dependency in dependencies:
                views.dependency.add_dependency({"module_id": module_id, "depends_on": dependency['module']['id']}, True)

    # If availabe, set the logic filename after knowing the database id of the module
    if logic and module_id:
        final_logic_filename = "logic_" + str(module_id) + ".py"
        sql, values = modules.utils.build_sql_instruction("UPDATE module", ["logicFilename"], final_logic_filename, "WHERE id="+str(module_id))
        modules.utils.db_execute_update_insert(mysql, sql, values, True)

    # 'Do, or do not, there is no try.'
    return(modules.utils.build_response_json(request.path, 200, {"id": module_id, "tree": tree}))  

"""
[Summary]: Delete logic file linked to a module.
[Returns]: Returns a success or error response
"""
@app.route('/api/module/<ID>/logic', methods=["DELETE"])
def delete_module_logic(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'DELETE': return
    
    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticatedAdmin(request)

    # Get information about module and remove logic file
    module = find_module(ID, True)

    if (module[0]['logic_filename']):
        try:
            os.remove(os.getcwd() + "/external/" + module[0]['logic_filename'])
        except OSError as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500)

    # The Delete request was a success, the user 'took the blue pill'.
    if (not internal_call):
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)


"""
[Summary]: Delete questions linked to a module.
[Returns]: Returns a success or error response
"""
@app.route('/api/module/<ID>/questions', methods=["DELETE"])
def delete_module_questions(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'DELETE': return
    
    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticatedAdmin(request)

    # Get the set of questions linked to this module.
    questions = find_module_questions(ID, True)
    if (questions):
        for question in questions:
            views.question.delete_question(question['id'], True)
    
    # Delete the module itself and all the sessions linked to him.
    # delete_module(ID, True)

    # The Delete request was a success, the user 'took the blue pill'.
    if (not internal_call):
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)

"""
[Summary]: Delete answers linked to a module.
[Returns]: Returns a success or error response
"""
@app.route('/api/module/<ID>/answers', methods=["DELETE"])
def delete_module_answers(ID, internal_call=False):
    if (not internal_call): 
        if request.method != 'DELETE': return

    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticatedAdmin(request)

    # Get the set of answers linked to this module.
        # Get the set of questions linked to this module.
    answers = find_module_answers(ID, True)
    if (answers):
        for answer in answers:
            views.answer.delete_answer(answer['id'], True)
    
    # Delete the module itself and all the sessions linked to him.
    # delete_module(ID, True)
    
    if (not internal_call):
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)


"""
[Summary]: Delete a module (partial delete - Linked questions and answers are not deleted)
[Returns]: Returns a success or error response
"""
@app.route('/api/module/<ID>', methods=["DELETE"])
def delete_module_partial(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'DELETE': return
    
    # 1. Check if the user has permissions to access this resource
    if (not internal_call):
        views.user.isAuthenticatedAdmin(request)

    # 2. Delete logic file associated
    delete_module_logic(ID, True)

    # 3. Connect to the database and delete the resource
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM module WHERE ID=%s", ID)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 4. The Delete request was a success, the user 'took the blue pill'.
    if (not internal_call): 
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)

"""
[Summary]: Fully delete a module (including sessions, linked questions and answers)
[Returns]: Returns a success or error response
"""
@app.route('/api/module/<ID>/full', methods=["DELETE"])
def delete_module_full(ID, internal_call=False):
    if (not internal_call): 
        if request.method != 'DELETE': return

    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticatedAdmin(request)

    # Get and delete the set of answers and questions linked to this module.
    delete_module_answers(ID, True)
    delete_module_questions(ID, True)
    
    # Delete the module itself and all the sessions linked to him.
    delete_module_partial(ID, True)
    
    if (not internal_call):
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)

"""
[Summary]: Updates a Module.
[Returns]: returns 200 if the operation was a success, 500 otherwise.
"""
@app.route('/api/module', methods=['PUT'])
def update_module():
    DEBUG=False
    # Check if the user has permissions to access this resource
    views.user.isAuthenticatedAdmin(request)
    # Delete the module but not to forget to preserve the session related to this module that  is being delete just for the sake of being easier to update is info based on the tree parsed
    if request.method != 'PUT': return
    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"id"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    

    module_id       = json_data['id']
    tree            = None
    # If there is a tree to update
    if ('tree' in json_data):
        modules.utils.console_log("[PUT]/api/module", "Tree exists")
        tree        = json_data['tree']
    # If the user has choosen to erase all questions
    if (tree is None):
        modules.utils.console_log("[PUT]/api/module", "No tree exists")
        sql     = "DELETE FROM module_question WHERE moduleID=%s"
        values  = module_id
        modules.utils.db_execute_update_insert(mysql, sql, values)

    #
    dependencies    = "dependencies" in json_data and json_data['dependencies'] or None
    recommendations = "recommendations" in json_data and json_data['recommendations'] or None
    shortname       = "shortname" in json_data and json_data['shortname'] or None
    fullname        = "fullname" in json_data and json_data['fullname'] or None
    displayname     = "displayname" in json_data and json_data['displayname'] or None
    avatar          = "avatar" in json_data and json_data['avatar'] or None
    description     = "description" in json_data and json_data['description'] or None
    type_id         = "type_id" in json_data and json_data['type_id'] or None
    logic           = "logic_filename" in json_data and "logic_"+str(module_id)+".py" or None
    createdon       = None
    updatedon       = datetime.now()
    
    # Build the SQL instruction using our handy function to build sql instructions.
    columns = [shortname and "shortname" or None, fullname and "fullname" or None, displayname and "displayname" or None, type_id and "typeID" or None, logic and "logicFilename" or None, avatar and "avatar" or None, description and "description" or None, createdon and "createdon" or None, updatedon and "updatedon" or None]
    values  = (shortname, fullname, displayname, type_id, logic, avatar, description, createdon, updatedon)
    where   = "WHERE id="+str(module_id)

    sql, values = modules.utils.build_sql_instruction("UPDATE module", columns, values, where)
    if (DEBUG): modules.utils.console_log("[PUT]/api/module", str(sql + " => " + str(values) + " " + where))

    # Update 
    modules.utils.db_execute_update_insert(mysql, sql, values)
    
    # Iterate the tree of module in order to update questions an answers of the module
    if ('tree' in json_data):
        for node in tree:   
            iterate_tree_nodes(recommendations, "UPDATE", module_id, node)

    # Update the dependency
    if (dependencies):
        for dependency in dependencies:
            flag_remove = "to_remove" in dependency and dependency['to_remove'] or None
            # Remove the dependency
            if (flag_remove):
                views.dependency.delete_dependency(dependency['id'], True)
            else:
                views.dependency.add_dependency({"module_id": module_id, "depends_on": dependency['module']['id']}, True)

    if (recommendations):
        # Check if there are any recommendation flagged to be removed, what is removed is not the recommentation but the mapping of a recommendation to the current module
        for recommendation in recommendations:
            flag_remove = "to_remove" in recommendation and recommendation['to_remove'] or None
            # Remove the recommendation
            if (flag_remove):
                views.recommendation.remove_recommendation_of_module(recommendation['id'], module_id, True)
            # Add a new recommendation
            else:
                # Store the mapping of question_answer and recommendations (DB table Recommendation_Question_Answer)
                # Get the question_answer id primary key value, through [question_id] and [answer_id]    
                for question_answer in recommendation['questions_answers']:
                    qa_res = views.question.find_question_answers_2(question_answer['question_id'], question_answer['answer_id'], True)
                    if (qa_res is None): return(modules.utils.build_response_json(request.path, 400)) 
                    qa_res = qa_res[0]
                    if (DEBUG): print("[SAM-API] [POST]/api/module - question_id = " + str(question_answer['question_id']) + ", answer_id=" + str(question_answer['answer_id']) + " => Question_Answer_id =" + str(qa_res['question_answer_id']))
                    question_answer['id'] = qa_res['question_answer_id']
                    print("!---->" + str(question_answer['id']))
                
                # Add the recommendation with the link between questions and answers
                views.recommendation.add_recommendation(recommendation)
    
    return(modules.utils.build_response_json(request.path, 200, {"id": module_id}))  

"""
[Summary]: Get modules.
[Returns]: Returns a set of modules.
"""
@app.route('/api/modules', methods=['GET'])
def get_modules():
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the modules from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, typeID, shortname, fullname, displayname, logicfilename, description, avatar, createdon, updatedon FROM module WHERE disable = 0")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.1. Check for empty results. 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']              = row[0]
            data['type_id']         = row[1]
            data['shortname']       = row[2]
            data['fullname']        = row[3]
            data['displayname']     = row[4]
            data['logic_filename']  = row[5]
            data['plugin']          = check_plugin(row[0], True)
            data['description']     = row[6]
            data['avatar']          = row[7]
            data['createdon']       = row[8]
            data['updatedon']       = row[9]
            datas.append(data)

        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young padawan'.
        return(modules.utils.build_response_json(request.path, 200, datas))    

"""
[Summary]: Get questions of each module.
[Returns]: Returns a set of modules.
"""
@app.route('/api/modules/questions', methods=['GET'])
def get_modules_questions():
    if request.method != 'GET': return

    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # Let's get the resource from the DB
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT DISTINCT module_id FROM view_module_questions_answers")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results. 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = []
        # Module IDs first
        for row in res:
            module = {}
            module['id']            = row[0]
            module['questions']     = find_module_questions(module['id'], True)
            datas.append(module)
    cursor.close()
    conn.close()
    
    # 'May the Force be with you, young padawan'.
    return(modules.utils.build_response_json(request.path, 200, datas))    

"""
[Summary]: Get answers of each module.
[Returns]: Returns a set of modules.
"""
@app.route('/api/modules/answers', methods=['GET'])
def get_modules_answers():
    if request.method != 'GET': return

    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # Let's get the resource from the DB
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT DISTINCT module_id FROM view_module_questions_answers")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results. 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = []
        # Module IDs first
        for row in res:
            module = {}
            module['id']            = row[0]
            module['answers']     = find_module_answers(module['id'], True)
            datas.append(module)
    cursor.close()
    conn.close()
    
    # 'May the Force be with you, young padawan'.
    return(modules.utils.build_response_json(request.path, 200, datas))    

"""
[Summary]: Get shortName and displayName of each module.
[Returns]: Returns a set of modules.
"""
def get_modules_short_displaynames():
    # Let's get the resource from the DB
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT shortname, displayName FROM module")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    short_names   = []
    display_names = []
    # Module IDs first
    for row in res:
        short_names.append(row[0])
        display_names.append(row[1])
    cursor.close()
    conn.close()
    
    return short_names, display_names   


"""
[Summary]: Finds a module.
[Returns]: Returns a module.
"""
@app.route('/api/module/<ID>', methods=['GET'])
def find_module(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # Check if the user has permissions to access this resource
    if (not internal_call): 
        views.user.isAuthenticated(request)
    
    # Get the tree of the module and other relevant information.
    tree            = (get_module_tree(str(ID), True))
    recommendations = (views.recommendation.find_recommendations_of_module(ID, True))
    dependencies    = (views.dependency.find_dependency_of_module(ID, True))
    
    if (not dependencies): dependencies = []
    if (not recommendations): recommendations = []

    # Let's get the modules from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, typeID, shortname, fullname, displayname, logicfilename, description, avatar, createdon, updatedon FROM module WHERE ID=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results. 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']              = row[0]
            data['type_id']         = row[1]
            data['shortname']       = row[2]
            data['fullname']        = row[3]
            data['displayname']     = row[4]
            data['logic_filename']  = row[5]
            data['description']     = row[6]
            data['avatar']          = row[7]
            data['createdon']       = row[8]
            data['updatedon']       = row[9]
            data['tree']            = tree
            data['recommendations'] = recommendations and recommendations or []
            data['dependencies']    = dependencies
            datas.append(data)
        cursor.close()
        conn.close()

        # 'May the Force be with you, young padawan'.
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, datas))
        else:
            return(datas)

"""
[Summary]: Finds questions linked to a module.
[Returns]: Returns a module.
"""
@app.route('/api/module/<ID>/questions', methods=['GET'])
def find_module_questions(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)


    # Let's get the questions of the module
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT DISTINCT question_id, question, createdon, updatedon FROM view_module_question WHERE module_id=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results. 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        datas = [] # Create a new nice empty array to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']              = row[0]
            data['content']         = row[1]
            data['createdon']       = row[2]
            data['updatedon']       = row[3]
            datas.append(data)
        cursor.close()
        conn.close()

        # 'May the Force be with you, young padawan'.
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, datas))
        else:
            return(datas)

"""
[Summary]: Finds answers linked to a module.
[Returns]: Returns a module.
"""
@app.route('/api/module/<ID>/answers', methods=['GET'])
def find_module_answers(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # Let's get the answers linked to the current module.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT DISTINCT answer_id, answer, createdon, updatedon FROM view_module_answers WHERE module_id=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results. 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        datas = [] # Create a new nice empty array to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']              = row[0]
            data['content']         = row[1]
            data['createdon']       = row[2]
            data['updatedon']       = row[3]
            datas.append(data)
        cursor.close()
        conn.close()

        # 'May the Force be with you, young padawan'.
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, datas))
        else:
            return(datas)

"""
[Summary]: Get the tree of the module. This tree contains all the questions and answers.
[Returns]: A set of questions, its children, and its answers.
"""
@app.route('/api/module/<pID>/tree', methods=['GET'])
def get_module_tree(pID, internal_call=False):
    # Do you want to add recommendations to the tree? For example, if an answer is X than the recommendation is Y, and so on. This feature is still experimental.
    add_recommendations_to_tree = False
    IDS = []
    if (not internal_call):
        if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # 1.1. Check if the user needs information about all modules available on the database.
    if (pID.lower() == "all"):
        try:
            conn    = mysql.connect()
            cursor  = conn.cursor()
            cursor.execute("SELECT ID FROM Module ORDER BY ID ASC")
            res = cursor.fetchall()
            if (len(res) != 0):
                for row in res:
                    IDS.append(int(row[0]))
            cursor.close()
            conn.close()
        except Exception as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    else:
        IDS.append(pID)

    datas = []
    for ID in IDS:
        # print(" Processing Data of Module " + str(ID))
        # 2. Let's get the main questions of the module.
        try:
            conn    = mysql.connect()
            cursor  = conn.cursor()
            cursor.execute("SELECT module_id, module_displayname, question_id, question, questionorder, multipleAnswers FROM view_module_question WHERE module_id = %s", ID)
            res = cursor.fetchall()
        except Exception as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500)
        
        # 2.2. Check for empty results - 'Fasten your seatbelts. It's going to be a bumpy night'.
        if (len(res) == 0):
            cursor.close()
            conn.close()
            if (len(IDS) == 1):
                if (not internal_call):
                    return(modules.utils.build_response_json(request.path, 404))
                else:
                    return None
            else:
                continue
        else:
            # 2.2.1. The initial set of the information about the module.
            for row in res: 
                data = {"id": row[0], "name": row[1]}
                break
            # 2.2.2. Map questions of the module to a JSON Python Object (dic).
            questions = []
            for row in res:
                question = {"id": row[2], "type": "question", "name": row[3], "multipleAnswers" : row[5], "order": row[4], "children": []}
                questions.append(question)
            data.update({"tree":  questions})

            cursor.close()
            conn.close()
        
        # 3. Recursively get each question child and corresponding data (question, answer, and so on).
        for question in data['tree']: 
            get_children(True, question, add_recommendations_to_tree)
             

        if (len(IDS) == 1):    
            # 4. 'May the Force be with you'.
            if (not internal_call):
                return(modules.utils.build_response_json(request.path, 200, data))
            else:
                #del data[request.path]
                return(data['tree'])
        else:
            datas.append(data)
    
    # 4. 'May the Force be with you'.
    if (not internal_call):
        return(modules.utils.build_response_json(request.path, 200, datas))
    else:
        del datas[request.path]
        # print("### = " + str(datas['tree']))
        return(datas['tree'])


"""
[Summary]: Auxiliary function to check if a subquestion is no longer linked to parent one. 
[Arguments]:
    - $parent$: Parent id.
    - $values$: Child id.
    - $trigger$; Answer id. 
"""
def subquestion_parent_changed(parent, child, trigger):
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        print("SELECT ID FROM question_has_child WHERE parent=%s AND child=%s AND ontrigger=%s", (parent, child, trigger))
        cursor.execute("SELECT ID FROM question_has_child WHERE parent=%s AND child=%s AND ontrigger=%s", (parent, child, trigger))
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)

    # 2.1. Check for empty results. 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(True)    
    else:
        cursor.close()
        conn.close()
        return(False)

"""
[Summary]: Auxiliary functions to check if an answer or question is no longer is parent or child.
[Arguments]:
    - $question_id$: Parent id.
    - $answer_id$: Child id.
"""
def parent_changed(question_id, answer_id):
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        print("SELECT ID FROM question_answer WHERE questionID=%s AND answerID=%s", (question_id, answer_id))
        cursor.execute("SELECT ID FROM question_answer WHERE questionID=%s AND answerID=%s", (question_id, answer_id))
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)

    # 2.1. Check for empty results. 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(True)    
    else:
        cursor.close()
        conn.close()
        return(False)

"""
[Summary]: When a new question or answer is added on the client side an ID is generated for each one. After that, the user is required to add recommendations. 
           These recommendations will be given taking into account if the user has selected a set of answers to a set of questions. The mapping of questions and 
           answers temporarily uses the previous generated ID. After the process of adding each question and answer to the database, that temporary ID needs to be 
           updated to the new one (i.e., the ID that identifies each question and answer on the database). 
[Arguments]:
    - $client_id$: The id temporary assigned (on the client side) to a question or answer.
    - $database_id$: The 'real' id of the question or answer that is used to update a recommendation.
    - $recommendations$: The list of recommendations.
    - $is_question$: Flag to ascertain if the mapping operation of client_id => database_id is to be performed on a question or an answer.
"""
def update_questions_answers_ids(client_id, database_id, recommendations, is_question):
    DEBUG = False
    if (DEBUG):
        if (is_question):
            print("[SAM-API] update_questions_answers_ids() => Trying to find client_question_id = " + str(client_id) + " in recommendations list.")
        else:
            print("[SAM-API] update_questions_answers_ids() => Trying to find client_question_id = " + str(client_id) + " in recommendations list.")
    
    if (recommendations):
        for recommendation in recommendations:
            # if ("questions_answers" not in recommendation): continue
            for question_answer in recommendation['questions_answers']:
                # Update the questions to the real ID
                if (is_question):
                    if ("client_question_id" in question_answer):
                        if (question_answer['client_question_id'] == client_id):
                            del question_answer['client_question_id']
                            question_answer['question_id'] = database_id
                            if (DEBUG): print("[SAM-API] update_questions_answers_ids() => Found it, updating node = " + str(question_answer))
                else:
                    if ("client_answer_id" in question_answer):
                        if (question_answer['client_answer_id'] == client_id):
                            del question_answer['client_answer_id']
                            question_answer['answer_id'] = database_id
                            if (DEBUG): print("[SAM-API] update_questions_answers_ids() => Found it, updating node = " + str(question_answer))

"""
[Summary]: Iterates the module tree that contains the mapping of questions and answers. This is an auxiliary function of add_module() and update_module().
[Arguments]:
    - $module_id$: Id of the newly created module.
    - $node$:  current node of the tree being processed. 
    - $p_node$: Previous node or parent node.
    - $p_p_node$: Parent of the parent node.
"""
def iterate_tree_nodes(recommendations, operation, module_id, c_node, p_node=None, p_p_node=None):
    debug=False
    # print("[SAM-API] Processing current node = '"+ str(c_node['name'])+"'")
    operation = operation.upper()

    # In the case of an UPDATE operation, we need to check if this question is available on the database; if not, 
    # this means that the user has added a new question/answer and the values are in need of being processed with an INSERT operation.
    # ---> We need to change the operation from UPDATE TO INSERT after encountering this situation. 
    # ---> We can check if a question/answer is NOT available on the database if c_node['id'] == null
    if (operation == "UPDATE" and (not c_node['id'])): 
        operation = "INSERT"

    # 1. Check if the current node is a question or an answer.
    if (c_node["type"] == "question"): 
        
        # 1.1. Add or update question - Table [Question].
        if (operation == "INSERT"):
            sql     = "INSERT INTO question (content, multipleAnswers) VALUES (%s, %s)"
            values  =  (c_node['name'], c_node['multipleAnswers'])
            exists_flag = False
            # Check if the question already exists (i.e. if c_node['id'] == null)
            if (not c_node['id']):
                c_node.update({"id": modules.utils.db_execute_update_insert(mysql, sql, values)})
                # By knowing the client_id update recommendations questions and answers to the database id (c_node['id']).
                update_questions_answers_ids(c_node['client_id'], c_node['id'], recommendations, True)

            if (debug): print("  -> [" + str(c_node["id"]) + "] = '" + sql + ", " + str(values))
        if (operation == "UPDATE"):
            sql     = "UPDATE question SET content=%s, multipleAnswers=%s WHERE ID=%s"
            values  = (c_node['name'], c_node['multipleAnswers'], c_node['id'])
            if (debug): print("  -> [" + str(c_node["id"]) + "] = '" + sql + ", " + str(values))
            modules.utils.db_execute_update_insert(mysql, sql, values)

        
        # 1.2. Add link to table [Module_Question] - Link question and the module together.
        # Be aware, that child questions are not added to this table. That is, only questions are mapped to modules.
        if (p_node is None):
            if (operation == "INSERT"):
                sql     = "INSERT INTO module_question (moduleID, questionID, questionOrder) VALUES (%s, %s, %s)"
                values  = (module_id,c_node['id'], 0)
                modules.utils.db_execute_update_insert(mysql, sql, values)
                if (debug): print("  -> [?] = '" + sql + ", " + str(values))

        # 1.3. Add Sub question to table [Question_has_Child] - Link question and subquestions by a trigger (i.e., answer).
        # Knowing that the current node is a parent, this is accomplish by checking if the parent was an answer. 
        if (p_node != None):
            if (p_node['type'] == "answer"): 

                if (operation == "INSERT"):
                    sql     = "INSERT INTO question_has_child (parent, child, ontrigger, questionOrder) VALUES (%s, %s, %s, %s)"
                    values  = (p_p_node['id'], c_node['id'], p_node['id'], 0)
                    modules.utils.db_execute_update_insert(mysql, sql, values)
                    if (debug): print("  -> [?] = '" + sql + ", " + str(values))
                
                if (operation == "UPDATE"):
                    if (subquestion_parent_changed(p_p_node['id'], c_node['id'], p_node['id'])):
                        if (debug): print("  -> [?] New Link detected")
                        # Remove the previous link
                        sql     = "DELETE FROM question_has_child WHERE child=%s"
                        values  = c_node['id']
                        if (debug): print("     -> '" + sql + ", " + str(values))
                        modules.utils.db_execute_update_insert(mysql, sql, values)
                        # Add the new link
                        sql     = "INSERT INTO question_has_child (parent, child, ontrigger, questionOrder) VALUES (%s, %s, %s, %s)"
                        values  = (p_p_node['id'], c_node['id'], p_node['id'], 0)
                        if (debug): print("     -> '" + sql + ", " + str(values))
                        modules.utils.db_execute_update_insert(mysql, sql, values)
    else: 
        # 1.1. Add or update answer - Table [Answer].
        if (operation == "INSERT"):
            sql     = "INSERT INTO answer (content) VALUES (%s)"
            values  = c_node['name']
            exists_flag = False
            # Check if the answer already exists (i.e. if c_node['id'] == null)
            if (not c_node['id']):
                # Check if the answer is similar or equal to one already available on the database, if so, use the id of the one that is equal
                # This is performed by checking the contents of an answer. No need to create a new answer on the database if one similar is already available.
                node_id = (modules.utils.db_already_exists(mysql, "SELECT id, content FROM answer WHERE content LIKE %s", c_node['name']))
                print(node_id)
                if (node_id == -1):
                    c_node.update({"id": modules.utils.db_execute_update_insert(mysql, sql, values)}) # Store the ID of the newly created answer.
                else:
                    c_node.update({"id": node_id}) # Store the ID of an answer that was previsouly inserted on the database. 

                # By knowing the client_id update recommendations questions and answers to the database id (c_node['id']).
                update_questions_answers_ids(c_node['client_id'], c_node['id'], recommendations, False)

            if (debug): print("  -> [" + str(c_node["id"]) + "] = '" + sql + ", " + str(values))
        
        if (operation == "UPDATE"):
            sql     = "UPDATE answer SET content=%s WHERE ID=%s"
            values  = (c_node['name'], c_node['id'])
            if (debug): print("  -> [" + str(c_node["id"]) + "] = '" + sql + ", " + str(values))
            modules.utils.db_execute_update_insert(mysql, sql, values)
        
        if (operation == "INSERT"):
            # 1.2. Add link to table [Question_Answer] - Link question and answer together.
            sql     = "INSERT INTO question_answer (questionID, answerID) VALUES (%s, %s)"
            values  = (p_node['id'], c_node['id'])
            modules.utils.db_execute_update_insert(mysql, sql, values)
            if (debug): print("  -> [?] = '" + sql + ", " + str(values))
        
        if (operation == "UPDATE"):
            # Check if the link between the current answer node and a question was changed (i.e., parent change).
            # If true remove the previous link and assigned the new one
            if (parent_changed(p_node['id'], c_node['id'])):
                # Remove the previous one
                if (debug): print("  -> [?] New Link detected")
                sql     = "DELETE FROM question_answer WHERE answerID=%s AND questionID IN (SELECT questionID From question_answer WHRE answerID=%s)"
                values  = (c_node['id'], c_node['id'])
                if (debug): print("    -> [?] = '" + sql + ", " + str(values))
                modules.utils.db_execute_update_insert(mysql, sql, values)
                # Add new updated link
                sql     = "INSERT INTO question_answer (questionID, answerID) VALUES (%s, %s)"
                values  = (p_node['id'], c_node['id'])
                modules.utils.db_execute_update_insert(mysql, sql, values)
                if (debug): print("    -> [?] = '" + sql + ", " + str(values))

    if (debug): print("\n")
    try:
        # Recursively iterate 
        for child in c_node['children']:
            iterate_tree_nodes(recommendations, operation, module_id, child, c_node, p_node)
    except:
        pass
    return

"""
[Summary]: Auxiliary function to get the sub-questions of a set of questions, and the sub-questions of 
           those, and so on. This is accomplished through our 'friendly neighbor' - recursivity. 
[Arguments]:
    - $initial$:  This flag must be set to true if it is the initial call of the recursive function.
    - $c_childs$: Array that contains the childs of a question ($question_js$ Python object), this must be initially empty.
    - $question$: Current question being analysed (has childs ?).
    - $question_js$: The JSON Python object being populate with data (question information, answers, and so on.)
[Returns]: Returns a JSON object with the mapping of all childs of a set of questions.
"""
def get_children(initial, question, add_recommendations_to_tree):
    children = question['children']
    debug = False
    if (debug): print("# Parsing question [%s] - %s" % (question['id'], question['name']))
    # 1. Get answers of the parent question.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT answer_id, answer FROM view_question_answer WHERE question_id=%s", question['id'])
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 1.2. Store, if available, answers of the parent question - An answer is a child of a parent question.
    if (len(res) != 0):
        for row in res:
            answer = { "id": row[0], "type": "answer", "name": row[1], "children" : []}
            children.append(answer)     
    cursor.close() # Clean the house nice & tidy.

    # 2. Check if the current question has children; IF not, return.
    #    This is the illusive break/return condition of this recursive function - 'Elementary, my dear Watson.'
    if (len(children) == 0): return None

    # Get recommendation(s) for the current answer and question.
    for child in children:
        if (child['type'] == 'question'): continue


    # 3. Get sub-questions triggered by an answer 
    for child in children:
        try:
            cursor  = conn.cursor()
            cursor.execute("SELECT child_id, question, questionOrder, ontrigger, multipleAnswers FROM view_question_childs WHERE parent_id=%s AND ontrigger=%s", (question['id'], child['id']))
            res = cursor.fetchall()
        except Exception as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500)
        
        # 3.1. Store it!
        if (len(res) != 0):
            for row in res:
                s_question = {"id": row[0], "name": row[1], "multipleAnswers": row[4], "type": "question","order": row[2],"trigger": row[3], "children": []}
                child['children'].append(s_question)
        
        # 3.2. If requested, and a sub-question is no where to be found for the current child, the list of recommendations will be added as children to the current answer.
        else:
            if (add_recommendations_to_tree):
                recommendations = (views.recommendation.find_recommendations_of_question_answer(question['id'], child['id'], True)).json
                # print(str(recommendations))
                if (recommendations != None): child['children'] = recommendations
            
            
    cursor.close()
    conn.close()

    # Debug
    if (debug):
        print("<!> Question [%s] ('%s') has the following answers:" % (question['id'], question['name']))
        for answer in children:
            if (answer['type'] == "answer"):
                print("  -> Answer ID[%d] - %s" % (answer['id'], answer['name']))
                for s_question in answer['children']:
                    print("     -> Question ID[%d] - %s" % (s_question['id'], s_question['name']))

    # 4. Recursive calls and python JSON object construction
    if (len(question['children']) != 0): question.update({"expanded": False})
    for answer in children:
        t_answer = answer
        # We need to go deeper in order to find the questions to be parsed to this recursive function.
        for question in answer['children']:
            t_answer.update({"expanded": False})
            if (question['type'] != 'recommendation'):
                get_children(False, question, add_recommendations_to_tree)
 
"""
[Summary]: Checks if a module is a plugin.
[Returns]: Returns a Boolean.
"""
@app.route('/api/module/<ID>/type', methods=['GET'])
def check_plugin (ID, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    tree = get_module_tree(str(ID), True)

    if (tree == None):
        plugin = True
    else:
        plugin = False

    if (not internal_call):
        return modules.utils.build_response_json(request.path, plugin)
    else:
        return plugin

Get Modules

GET /api/module

Synopsis

Get the list of modules installed in the platform.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Id of the module.

• type_id (int) – Module type id.

• shortname (string) – Unique short name or abbreviation.

• description (string) – Module description.

• fullname (string) – Full name of the module.

• displayname (string) – Module display name that can be used by a frontend.

• avatar (string) – Avatar of the user (i.e., location in disk).

• logic_filename (string) – Filename of the file containing the dynamic logic of the module.

• plugin (boolean) – A flag that sets if the current module is a plugin.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – status code.

Status Codes

• 200 OK – Module successfully retrieved.

• 500 Internal Server Error – Fail to retrieve module.

Example Response

{
   "/api/modules":{
      "content":[
         {
            "id":1,
            "type_id":null,
            "shortname":"SRE",
            "fullname":"Security Requirements Elicitation",
            "description":null,
            "displayname":"Security Requirements",
            "avatar":null,
            "logic_filename":null,
            "plugin":false,
            "createdon":"Tue, 28 Sep 2021 13:42:48 GMT",
            "updatedon":"Tue, 28 Sep 2021 13:48:19 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/module/(int: id)

Synopsis

Get a module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id – Id of the module.

Response JSON Object

• id (int) – Id of the module.

• type_id (int) – Module type id.

• dependencies (array) – An array that contains the set of modules that the current module depends on.

• shortname (string) – Unique short name or abbreviation.

• displayname (string) – Module display name that can be used by a frontend.

• fullname (string) – Full name of the module.

• description (string) – Module description.

• logic_filename (string) – Filename of the file containing the dynamic logic of the module.

• avatar (string) – Avatar of the user (i.e., location in disk).

• recommendations (array) – Set of recommendations mapped to this module.

• tree (array) – An array that contains the set of questions and answers mapped for the current module.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Module successfully retrieved.

• 500 Internal Server Error – Fail to retrieve module.

Example Response

{
   "/api/module/1":{
      "content":[
         {
            "id":1,
            "type_id":null,
            "dependencies":[],
            "shortname":"SRE",
            "displayname":"Security Requirements",
            "fullname":"Security Requirements Elicitation",
            "description":null,
            "logic_filename":null,
            "avatar":null,
            "recommendations":[
               {
                  "id":1,
                  "content":"Confidentiality",
                  "questions_answers":[
                     {
                        "id":1,
                        "answer_id":1,
                        "question_id":1,
                        "createdon":"Fri, 19 Nov 2021 12:54:49 GMT",
                        "updatedon":"Fri, 19 Nov 2021 12:54:49 GMT"
                     }
                  ],
                  "createdon":"Fri, 19 Nov 2021 12:54:49 GMT",
                  "updatedon":"Fri, 19 Nov 2021 12:54:49 GMT"
               }
            ],
            "tree":[
               {
                  "id":1,
                  "order":0,
                  "name":"What is the domain of your IoT system ?",
                  "multipleAnswers":0,
                  "type":"question",
                  "children":[
                     {
                        "id":1,
                        "name":"Smart home",
                        "type":"answer",
                        "children":[],
                     },
                     {
                        "id":2,
                        "name":"Smart Healthcare",
                        "type":"answer",
                        "children":[]
                     }
                  ],
               }
            ],
            "createdon":"Fri, 19 Nov 2021 12:54:49 GMT",
            "updatedon":"Fri, 19 Nov 2021 12:54:49 GMT"
         }
      ],
      "status":200
   }
}

Get Module Type

GET /api/module/(int: id)/type

Synopsis

Get the type of module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id – Id of the module.

Response JSON Object

• status (boolean) – A flag that sets if the current module is a plugin, true if the correct module is a plugin, false otherwise.

Status Codes

• 200 OK – Module type successfully retrieved.

• 500 Internal Server Error – Fail to retrieve module type information.

Note

A module plugin comprises questions and answers, while a module that is not a plugin fully depends on other modules to produce output.

Example Response

{
   "/api/module/1/type":{
      "status":false
   }
}

Get Questions/Answers of a Module

GET /api/module/(int: id)/tree

Synopsis

Get the tree array of questions and answers of a module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id – Id of the module.

Response JSON Object

• id (int) – Id of the current question or answer in the array depending of the type.

• order (int) – The sequencial number of the question.

• children (array) – The current module has a set of questions or answers that are mapped to this array.

• name (string) – The content/text of the current question.

• type (string) – Defines if the current element in the tree array is a question or an answer.

• multipleAnswers (boolean) – Defines if the user can select multiple answers for the current question.

• status (int) – status code.

Status Codes

• 200 OK – Module tree successfully retrieved.

• 500 Internal Server Error – Fail to retrieve tree of the module.

Note

Please, consider using something like, for example, the react-sortable-tree react component to develop a proper user interface to interact and manage the data returned by this service.

Example Response

{
   "/api/module/1/tree":{
      "tree":[
         {
            "id":1,
            "order":0,
            "name":"What is the domain of your IoT system ?",
            "multipleAnswers":0,
            "type":"question"
            "children":[
               {
                  "id":1,
                  "name":"Smart home",
                  "type":"answer",
                  "children":[]
               },
               {
                  "id":2,
                  "name":"Smart Healthcare",
                  "type":"answer",
                  "children":[]
               }
            ],
         }
      ],
      "status":200
   }
}

Get Questions of Modules

GET /api/module/questions

Synopsis

Get the list of questions mapped to each module.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Module or question id.

• questions (array) – Array of questions.

• status (int) – status code.

Status Codes

• 200 OK – Module’s questions successfully retrieved.

• 500 Internal Server Error – Fail to retrieve module’s questions.

Example Response

{
   "/api/modules/questions": {
      "content": [
         {
         "id": 1,
         "questions": [
            {
               "id": 1,
               "content": "What is the domain of your IoT system ?",
               "createdon": "Fri, 19 Nov 2021 15:29:18 GMT",
               "updatedon": "Fri, 19 Nov 2021 15:29:18 GMT"
            }
         ]
         }
      ],
      "status": 200
   }
}

---

GET /api/module/(int: id)/questions

Synopsis

Get the list of questions mapped to a module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id – Id of the module.

Response JSON Object

• id (int) – Module or question id.

• questions (array) – Array of questions.

• status (int) – status code.

Status Codes

• 200 OK – Module’s questions successfully retrieved.

• 500 Internal Server Error – Fail to retrieve module’s questions.

Example Response

{
   "/api/modules/questions": {
      "content": [
         {
         "id": 1,
         "questions": [
            {
               "id": 1,
               "content": "What is the domain of your IoT system ?",
               "createdon": "Fri, 19 Nov 2021 15:29:18 GMT",
               "updatedon": "Fri, 19 Nov 2021 15:29:18 GMT"
            }
         ]
         }
      ],
      "status": 200
   }
}

Get Modules Answers

GET /api/module/answers

Synopsis

Get the list of answers mapped to each module.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Module or answer id.

• answers (array) – Array of answers.

• status (int) – status code.

Status Codes

• 200 OK – Module’s answers successfully retrieved.

• 500 Internal Server Error – Fail to retrieve module’s answers.

Example Response

{
   "/api/modules/answers":{
      "content":[
         {
            "id":1
            "answers":[
               {
                  "id":1,
                  "content":"Smart home",
                  "createdon":"Fri, 19 Nov 2021 15:29:18 GMT",
                  "updatedon":"Fri, 19 Nov 2021 15:29:18 GMT"
               },
               {
                  "id":2,
                  "content":"Smart Healthcare",
                  "createdon":"Fri, 19 Nov 2021 15:29:18 GMT",
                  "updatedon":"Fri, 19 Nov 2021 15:29:18 GMT"
               }
            ]
         }
      ],
      "status":200
   }
}

---

GET /api/module/(int: id)/answers

Synopsis

Get the list of answers mapped to a module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id – Id of the module.

Response JSON Object

• id (int) – Module or answer id.

• answers (array) – Array of answers.

• status (int) – status code.

Status Codes

• 200 OK – Module’s answers successfully retrieved.

• 500 Internal Server Error – Fail to retrieve module’s answers.

Example Response

{
   "/api/modules/answers":{
      "content":[
         {
            "id":1
            "answers":[
               {
                  "id":1,
                  "content":"Smart home",
                  "createdon":"Fri, 19 Nov 2021 15:29:18 GMT",
                  "updatedon":"Fri, 19 Nov 2021 15:29:18 GMT"
               },
               {
                  "id":2,
                  "content":"Smart Healthcare",
                  "createdon":"Fri, 19 Nov 2021 15:29:18 GMT",
                  "updatedon":"Fri, 19 Nov 2021 15:29:18 GMT"
               }
            ]
         }
      ],
      "status":200
   }
}

Add Module

POST /api/module

Synopsis

Add a new module.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• shortname (string) – Unique short name or abbreviation of the module.

• fullname (string) – Full name of the module.

• displayname (string) – Module display name that can be used by a frontend.

• description (string) – Module description.

• tree (array) – Array of questions and answers mapped to the module.

• recommendations (array) – Array of recommendations mapped to a question id and answer id.

• dependencies (array) – An array that contains the set of modules that the current module depends on.

Status Codes

• 200 OK – Module successfully added.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to add module.

Important

The client_id field is a temporary id for a question or an answer that may not yet exist in the database – This temporary id is assigned by a client. An identical situation exists for client_question_id and client_answer_id:

Note

Each question can trigger a set of answers or questions (tree field).

Note

Each module can only be triggered if a module dependency was satisfied (i.e., the module described in the field dependencies was previously executed by the user).

Example Request

{
   "shortname":"SRE",
   "fullname":"Security Requirements Elicitation",
   "displayname":"Security Requirements",
   "description":"Module description",
   "tree":[
      {
         "id":null,
         "client_id":0,
         "type":"question",
         "name":"What is the domain of your IoT system ?",
         "multipleAnswers":false,
         "children":[
            {
               "id":null,
               "client_id":1,
               "name":"Smart home",
               "type":"answer",
               "multipleAnswers":false,
               "children":[
                  {
                     "id":null,
                     "client_id":2,
                     "name":"Will the sytem have a user LogIn ?",
                     "type":"question",
                     "children":[
                        {
                           "id":null,
                           "client_id":3,
                           "name":"Yes",
                           "type":"answer",
                           "children":[

                           ]
                        },
                        {
                           "id":null,
                           "client_id":4,
                           "name":"No",
                           "type":"answer",
                           "children":[

                           ]
                        }
                     ]
                  }
               ]
            },
            {
               "id":null,
               "client_id":5,
               "name":"Smart Healthcare",
               "type":"answer",
               "multipleAnswers":false,
               "children":[
                  {
                     "id":null,
                     "client_id":6,
                     "name":"Yes",
                     "type":"answer",
                     "children":[

                     ]
                  },
                  {
                     "id":null,
                     "client_id":7,
                     "name":"No",
                     "type":"answer",
                     "children":[

                     ]
                  }
               ]
            }
         ]
      }
   ],
   "recommendations":[
      {
         "id":null,
         "content":"Confidentiality",
         "questions_answers":[
            {
               "client_question_id":0,
               "client_answer_id":1
            }
         ]
      }
   ],
   "dependencies":[
      {
         "module":{
            "id":2
         }
      }
   ]
}

Edit Module

PUT /api/module

Synopsis

Edit a module.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• id (int) – Id of the module to edit.

• shortname (string) – Unique short name or abbreviation of the module.

• fullname (string) – Full name of the module.

• displayname (string) – Module display name that can be used by a frontend.

Response JSON Object

• status (int) – Status code

Status Codes

• 200 OK – Module successfully updated.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to update module.

Example Request

{
   "id":1,
   "shortname":"SREU",
   "fullname":"Security Requirements Elicitation Updated",
   "displayname":"Security Requirements Updated"
}

Note

Questions, answers, recommendations and dependencies of the module can also be updated using this service by following the same JSON object provide as example in the /api/module (add module) service.

Example Response

{"/api/module":{"status":200}}

Remove Module

DELETE /api/module/(int: id)

Synopsis

Performs a partial delete of a Module. That is, only the module and those sessions linked are deleted - Linked questions and associated answers are not delete.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the module to partially delete.

Status Codes

• 200 OK – Module successfully removed.

• 500 Internal Server Error – Fail to remove module.

DELETE /api/module/(int: id)/full

Synopsis

Fully removes a module (including sessions, linked questions, and answers).

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the module to fully delete.

Status Codes

• 200 OK – Module successfully removed.

• 500 Internal Server Error – Fail to remove module.

DELETE /api/module/(int: id)/questions

Synopsis

Removes all questions mapped to the module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the module.

Status Codes

• 200 OK – Module questions successfully removed.

• 500 Internal Server Error – Fail to remove module questions.

DELETE /api/module/(int: id)/answers

Synopsis

Removes all answers mapped to the module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the module.

Status Codes

• 200 OK – Module answers successfully removed.

• 500 Internal Server Error – Fail to remove module answers.

DELETE /api/module/(int: id)/logic

Synopsis

Removes the logic file mapped to the module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the module.

Status Codes

• 200 OK – Module answers successfully removed.

• 500 Internal Server Error – Fail to remove module answers.

Dependencies Services API

This section includes details concerning services developed for the dependency entity implemented in

dependency.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
from api import app, mysql
from flask import request
import modules.error_handlers, modules.utils # SAM's modules
import views.user, views.module # SAM's views

"""
[Summary]: Adds a new dependency to the database.
[Returns]: Response result.
"""
@app.route('/api/dependency', methods=['POST'])
def add_dependency(json_internal_data=None, internal_call=False):
    DEBUG=True
    if (not internal_call):
        if request.method != 'POST': return
    
    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    if (not internal_call):
        json_data = request.get_json()
    else:
        json_data = json_internal_data

    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): 
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 400))
        else:
            modules.utils.console_log("[POST]/api/dependency", "json_data is None")
            return(None)
   
    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"module_id", "depends_on"})):
        if (not internal_call):
            raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    
        else:
            modules.utils.console_log("[POST]/api/dependency", "Some required key or value is missing from the JSON object")

    module_id   = json_data['module_id']
    depends_on  = json_data['depends_on']
    createdon   = "createdon" in json_data and json_data['createdon'] or None
    updatedon   = "updatedon" in json_data and json_data['updatedon'] or None
    
    # Build the SQL instruction using our handy function to build sql instructions.
    values  = (module_id, depends_on, createdon, updatedon)
    columns = ["moduleID", "dependsOn", createdon and "createdon" or None, updatedon and "updatedon" or None]
    sql, values = modules.utils.build_sql_instruction("INSERT INTO dependency", columns, values)
    
    # Add
    n_id = modules.utils.db_execute_update_insert(mysql, sql, values, True)

    if (n_id is None):
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 400))
        else:
            return(None)
    else:
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, {"id": n_id}))
        else:
            return(n_id)

"""
[Summary]: Updates a dependency.
[Returns]: Response result.
"""
@app.route('/api/dependency', methods=['PUT'])
def update_dependency(json_internal_data=None, internal_call=False):
    DEBUG=True
    if (not internal_call):
        if request.method != 'PUT': return
    
    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    if (not internal_call):
        json_data = request.get_json()
    else:
        json_data = json_internal_data
    
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): 
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 400)) 
        else:
            modules.utils.console_log("[PUT]/api/dependency", "json_data is None")
            return(None)

    dependency_id_available = True
    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"id"})):
        dependency_id_available = False
        if (not modules.utils.valid_json(json_data, {"module_id", "depends_on", "p_depends_on"})):
            raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    
        

    module_id     = "module_id"     in json_data and json_data['module_id'] or None
    depends_on    = "depends_on"    in json_data and json_data['depends_on'] or None     # New dependency
    p_depends_on  = "p_depends_on"  in json_data and json_data['p_depends_on'] or None   # Previous dependency
    createdon     = "createdon"     in json_data and json_data['createdon'] or None
    updatedon     = "updatedon"     in json_data and json_data['updatedon'] or None

    # IF required, get the ID of the dependency taking into account the id of the module and the id of the module that it depends on.
    if (not dependency_id_available):
        json_tmp = find_dependency_of_module_2(module_id, p_depends_on, True)
        if (not json_tmp):
            raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the temporary JSON object", 400)    
        json_data['id'] = json_tmp['id']
    
    # Build the SQL instruction using our handy function to build sql instructions.
    values  = (module_id, depends_on, createdon, updatedon)
    columns = [module_id and "moduleID" or None, depends_on and "dependsOn" or None, createdon and "createdon" or None, updatedon and "updatedOn" or None]
    where   = "WHERE id="+str(json_data['id'])

    # Check if there is anything to update (i.e. frontend developer has not sent any values to update).
    if (len(values) == 0): return(modules.utils.build_response_json(request.path, 200))   

    sql, values = modules.utils.build_sql_instruction("UPDATE dependency", columns, values, where)
    if (DEBUG): modules.utils.console_log("[PUT]/api/dependency", sql + " " + str(values))

    # Update resource
    modules.utils.db_execute_update_insert(mysql, sql, values)

    if (not internal_call):
        return(modules.utils.build_response_json(request.path, 200))
    else:
        return(True)

"""
[Summary]: Get dependencies.
[Returns]: Response result.
"""
@app.route('/api/dependencies')
def get_dependency():
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, moduleID, dependsOn, createdOn, UpdatedOn FROM dependency")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['module_id']   = row[1]
            data['depends_on']  = row[2]
            data['createdon']   = row[3]
            data['updatedon']   = row[4]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas)) 

"""
[Summary]: Finds a dependency.
[Returns]: Response result.
"""
@app.route('/api/dependency/<ID>', methods=['GET'])
def find_dependency(ID):
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, moduleID, dependsOn, createdOn, UpdatedOn FROM dependency WHERE ID=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['module_id']   = row[1]
            data['depends_on']  = row[2]
            data['createdon']   = row[3]
            data['updatedon']   = row[4]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas)) 

"""
[Summary]: Finds a dependency of a module
[Returns]: Response result.
"""
@app.route('/api/dependency/module/<ID>', methods=['GET'])
def find_dependency_of_module(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT dependency_id, depends_module_id, createdOn, updatedOn FROM view_module_dependency WHERE module_ID=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404)) 
        else:
            return None
    else:
        datas = []
        for row in res:
            data = {}
            data['id']                      = row[0]
            t_module = views.module.find_module(row[1], True)
            module = {}
            module['id']                    = t_module[0]['id']
            module['fullname']              = t_module[0]['fullname']
            module['displayname']           = t_module[0]['displayname']
            module['shortname']             = t_module[0]['shortname']
            data['module']                  = module
            data['createdon']               = row[2]
            data['updatedon']               = row[3]
            datas.append(data)
        cursor.close()
        conn.close()
        
        # 3. 'May the Force be with you, young master'.
        if (not internal_call): 
            return(modules.utils.build_response_json(request.path, 200, datas)) 
        else:
            return(datas)


"""
[Summary]: Finds a dependency of a module, taking as arguments the id of the current module and the id of the module that it depends on.
[Returns]: Response result.
"""
@app.route('/api/dependency/module/<module_id>/depends/<depends_on_module_id>', methods=['GET'])
def find_dependency_of_module_2(module_id, depends_on_module_id, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        print("--->" + "SELECT dependency_id, module_id, depends_module_id, createdOn, updatedOn FROM view_module_dependency WHERE module_ID=%s AND depends_module_id=%s", (module_id, depends_on_module_id))
        cursor.execute("SELECT dependency_id, module_id, depends_module_id, createdOn, updatedOn FROM view_module_dependency WHERE module_ID=%s AND depends_module_id=%s", (module_id, depends_on_module_id))
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404)) 
        else:
            return None
    else:
        data = {}
        for row in res:
            data['id']                      = row[0]
            data['module_id']               = row[1]
            data['depends_on_module_id']    = row[2]
            data['createdon']               = row[2]
            data['updatedon']               = row[3]
        cursor.close()
        conn.close()
        
        # 3. 'May the Force be with you, young master'.
        if (not internal_call): 
            return(modules.utils.build_response_json(request.path, 200, data)) 
        else:
            return(data)


"""
[Summary]: Delete a dependency by id.
[Returns]: Returns a success or error response
"""
@app.route('/api/dependency/<dependency_id>', methods=["DELETE"])
def delete_dependency(dependency_id, internal_call=False):
    if (not internal_call):
        if request.method != 'DELETE': return

    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # Connect to the database and delete the resource
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM dependency WHERE ID=%s", dependency_id)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # The Delete request was a success, the user 'took the blue pill'.
    if (not internal_call):
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)

Get Dependencies

GET /api/dependencies

Synopsis

Get dependencies of a module.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Id of the dependency.

• module_id (int) – Id of the module.

• depends_on (int) – Id of the module that the module_id depends on.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Dependencies successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve dependencies.

Example Response

{
   "/api/dependencies":{
      "content":[
         {
            "id":1,
            "module_id":1,
            "depends_on":2,
            "createdon":"Sat, 20 Nov 2021 13:00:50 GMT",
            "updatedon":"Sat, 20 Nov 2021 13:00:50 GMT"
         }
      ],
      "status":200
   }
}

Note

The depends_on parameter describes the id of the module that the current module_id depends on.

---

GET /api/dependency/(int: id)

Synopsis

Get dependency identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the dependency.

Response JSON Object

• id (int) – Id of the dependency.

• module_id (int) – Id of the module.

• depends_on (int) – Id of the module that the module_id depends on.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Dependency successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve dependency.

Example Response

{
   "/api/dependency/1":{
      "content":[
         {
            "id":1,
            "module_id":1,
            "depends_on":2,
            "createdon":"Sat, 20 Nov 2021 13:00:50 GMT",
            "updatedon":"Sat, 20 Nov 2021 13:00:50 GMT"
         }
      ],
      "status":200
   }
}

Note

The depends_on parameter describes the id of the module that the current module_id depends on.

---

GET /api/dependency/module/(int: id)

Synopsis

Get dependencies of a module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the module.

Response JSON Object

• id (int) – Id of the dependency and dependecy module.

• module (object) – Information of the module that module id depends on.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Dependencies successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve dependencies.

Example Response

{
   "/api/dependency/module/2":{
      "content":[
         {
            "id":1,
            "module":{
               "id":1,
               "shortname":"SRE",
               "fullname":"Security Requirements Elicitation",
               "displayname":"Security Requirements"
            },
            "createdon":"Wed, 17 Nov 2021 14:14:26 GMT",
            "updatedon":"Wed, 17 Nov 2021 14:14:26 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/dependency/module/(int: id)/depends/(int: id)

Synopsis

Get dependency information of a module id that depends on module id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the module or id of the module it depends on.

Response JSON Object

• id (int) – Id of the dependency.

• module_id (int) – Id of the module.

• depends_on_module_id (int) – Id of the module that the module_id depends on.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Dependency successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve dependency.

Example Response

{
   "/api/dependency/module/2/depends/1":{
      "id":1,
      "module_id":2,
      "depends_on_module_id":1,
      "createdon":"Sat, 20 Nov 2021 13:00:50 GMT",
      "updatedon":"Sat, 20 Nov 2021 13:00:50 GMT",
      "status":200
   }
}

Add Dependency

POST /api/dependency

Synopsis

Add a new dependency.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• id (int) – Id of the dependency.

• module_id (int) – Id of the module.

• depends_on (int) – Id of the module that the module_id depends on.

Response JSON Object

• id (int) – The id of new dependency.

• status (int) – Status code.

Status Codes

• 200 OK – Dependency successfully added.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to add dependency.

Example Request

{"module_id":1, "depends_on":2}

Example Response

{"/api/dependency":{"id":2, "status":200}}

Edit Dependency

PUT /api/dependency

Synopsis

Updated a dependency identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• id (int) – Id of the dependency.

• module_id (int) – Id of the module.

• depends_on (int) – Id of the module that the module_id depends on.

• depends_on_p (int) – Id of the module that the module_id previously depended on.

Response JSON Object

• id (int) – The id of new dependency.

• status (int) – Status code.

Status Codes

• 200 OK – Dependency successfully updated.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to updated dependency.

Example Request

{"id":2, "module_id":1, "depends_on":3, "p_depends_on":2}

Example Response

{"/api/dependency":{"id":3, "status":200}}

Remove Dependency

DELETE /api/dependency/(int: id)

Synopsis

Remove a dependency identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Form Parameters

• id – The id of dependency to remove.

Response JSON Object

• status (int) – Status code.

Status Codes

• 200 OK – Dependency successfully removed.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to remove dependency.

Example Response

{"/api/dependency":{"status":200}}

Questions Services API

This section includes details concerning services developed for the question entity implemented in

question.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
from api import app, mysql
from flask import request
import modules.error_handlers, modules.utils # SAM's modules
import views.user, views.answer, views.module # SAM's views

"""
[Summary]: Adds a new question to the database.
[Returns]: Response result.
"""
@app.route('/api/question', methods=['POST'])
def add_question():
    DEBUG=True
    if request.method != 'POST': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"content", "description"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    

    content     = json_data['content']
    description = json_data['description']
    createdon   = "createdon" in json_data and json_data['createdon'] or None
    updatedon   = "updatedon" in json_data and json_data['updatedon'] or None
    
    # Build the SQL instruction using our handy function to build sql instructions.
    values = (content, description, createdon, updatedon)
    sql, values = modules.utils.build_sql_instruction("INSERT INTO question", ["content", "description", createdon and "createdon" or None, updatedon and "updatedon" or None], values)
    if (DEBUG): print("[SAM-API]: [POST]/api/question - " + sql)

    # Add
    n_id = modules.utils.db_execute_update_insert(mysql, sql, values)
    if (n_id is None):
        return(modules.utils.build_response_json(request.path, 400))  
    else:
        return(modules.utils.build_response_json(request.path, 200, {"id": n_id}))  


"""
[Summary]: Delete a question
[Returns]: Returns a success or error response
"""
@app.route('/api/question/<ID>', methods=["DELETE"])
def delete_question(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'DELETE': return
    
    # 1. Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # 2. Connect to the database and delete the resource
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM question WHERE ID=%s", ID)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 3. The Delete request was a success, the user 'took the blue pill'.
    if (not internal_call):
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)

"""
[Summary]: Updates a question.
[Returns]: Response result.
"""
@app.route('/api/question', methods=['PUT'])
def update_question():
    DEBUG=True
    if request.method != 'PUT': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"id"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    

    content     = "content"     in json_data and json_data['content'] or None
    description = "description" in json_data and json_data['description'] or None
    createdon   = "createdon"   in json_data and json_data['createdon'] or None
    updatedon   = "updatedon"   in json_data and json_data['updatedon'] or None

    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Build the SQL instruction using our handy function to build sql instructions.
    values  = (content, description, createdon, updatedon)
    columns = [content and "content" or None, description and "description" or None, createdon and "createdon" or None, updatedon and "updatedOn" or None]
    where   = "WHERE id="+str(json_data['id'])
    # Check if there is anything to update (i.e. frontend developer has not sent any values to update).
    if (len(values) == 0): return(modules.utils.build_response_json(request.path, 200))   

    sql, values = modules.utils.build_sql_instruction("UPDATE question", columns, values, where)
    if (DEBUG): print("[SAM-API]: [PUT]/api/question - " + sql + " " + str(values))

    # Update Recommendation
    modules.utils.db_execute_update_insert(mysql, sql, values)

    return(modules.utils.build_response_json(request.path, 200))   

"""
[Summary]: Get Questions.
[Returns]: Response result.
"""
@app.route('/api/questions')
def get_questions():
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT id, content, description, createdOn, updatedOn FROM question")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']      = row[0]
            data['content'] = row[1]
            data['description'] = row[2]
            data['type']    = 'question'
            data['modules'] = find_modules_of_question(data['id'])
            data['createdon']   = row[3]
            data['updatedon']   = row[4]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas)) 

"""
[Summary]: Finds the list of modules linked to a question
[Returns]: A list of modules or an empty array if None are found.
"""
def find_modules_of_question(question_id):
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT module_id FROM view_module_question WHERE question_id=%s", question_id)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        # Check if this question is a child of another question, triggered by an answer, were the parent belongs to a module.
        # We need to do this because sub-questions, triggered by an answer, are not directly linked to a module. 
        # In order to find the module that the sub-question belongs, we need to find its parent.
        try:
            conn    = mysql.connect()
            cursor  = conn.cursor()
            cursor.execute("SELECT parent FROM question_has_child WHERE child=%s", question_id)
            res = cursor.fetchall()
        except Exception as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500)
        
        if (len(res) == 0):
            cursor.close()
            conn.close()
            return([]) 
        else:
            l_modules = []
            for row in res:
                modules = find_modules_of_question(row[0])
                l_modules.append(modules)
            #
            f_list_modules = []
            for modules in l_modules:
                for module in modules:
                    if module not in f_list_modules:
                        f_list_modules.append(module)
            return(f_list_modules)
            cursor.close()
            conn.close()
    else:
        modules = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            module = views.module.find_module(row[0], True)[0]
            del module['tree']
            del module['dependencies']
            del module['recommendations']
            modules.append(module)
        cursor.close()
        conn.close()
       
        # 'May the Force be with you, young master'.
        return(modules)

"""
[Summary]: Finds Question.
[Returns]: Response result.
"""
@app.route('/api/question/<ID>', methods=['GET'])
def find_question(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    if (not internal_call):
        views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID as question_id, content, description, createdOn, updatedOn FROM question WHERE ID=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']      = row[0]
            data['content'] = row[1]
            data['type']    = 'question'
            datas.append(data)
        cursor.close()
        conn.close()
        
        # 3. 'May the Force be with you, young master'.
        if (not internal_call): 
            return(modules.utils.build_response_json(request.path, 200, datas)) 
        else:
            return(datas)

"""
[Summary]: Finds Answers of a Question by question ID ans answerID- [Question_Answer] Table.
[Returns]: Response result.
"""
@app.route('/api/question/<question_id>/answer/<answer_id>', methods=['GET'])
def find_question_answers_2(question_id, answer_id, internal_call=False):
    if (request.method != 'GET' and not internal_call): return

    
    # 1. Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT question_answer_id, question_id, question, answer_id, answer FROM view_question_answer where question_id=%s and answer_id=%s", (question_id, answer_id))
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['question_answer_id']  = row[0]
            data['question_id']         = row[1]
            data['question_content']    = row[2]
            data['answer_id']           = row[3]
            data['answer_content']      = row[4]
            datas.append(data)
        cursor.close()
        conn.close()
        
        # 3. 'May the Force be with you, young master'.
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, datas))
        else:
            return(datas)

"""
[Summary]: Finds Answers of a Question - [Question_Answer] Table.
[Returns]: Response result.
"""
@app.route('/api/question/<ID>/answers', methods=['GET'])
def find_question_answers(ID):
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT question_answer_id, question_id, question, answer_id, answer FROM view_question_answer where question_id=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['question_answer_id']  = row[0]
            data['question_id']         = row[1]
            data['question_content']    = row[2]
            data['answer_id']           = row[3]
            data['answer_content']      = row[4]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas))    


"""
[Summary]: Gets Answers of a Questions - [Question_Answer] Table.
[Returns]: Response result.
"""
@app.route('/api/questions/answers', methods=['GET'])
def get_questions_answers():
   
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the questions from the database 
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT question_answer_id, question_id, question, answer_id, answer FROM view_question_answer")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['question_answer_id']  = row[0]
            data['question_id']         = row[1]
            data['question_content']    = row[2]
            data['answer_id']           = row[3]
            data['answer_content']      = row[4]
            datas.append(data)
    
    cursor.close()
    conn.close()
    # 3. 'May the Force be with you, young master'.
    return(modules.utils.build_response_json(request.path, 200, datas))    

Get Questions

GET /api/questions

Synopsis

Get all questions.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Id of the current question.

• content (string) – The question.

• description (string) – Question description.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – status code.

Status Codes

• 200 OK – Questions successfully retrieved.

• 500 Internal Server Error – Fail to retrieve questions.

Example Response

{
   "/api/questions":{
      "content":[
         {
            "id":3,
            "content":"What is the name of ... ?",
            "description":"Test question description",
            "modules":[],
            "createdon":"Sun, 20 Sep 2020 09:00:00 GMT",
            "updatedon":"Sun, 20 Sep 2020 09:00:00 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/question/(int: id)

Synopsis

Get a question identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – id of the question.

Response JSON Object

• id (int) – Id of the question.

• content (string) – The question.

• status (int) – Status code.

Status Codes

• 200 OK – Question successfully retrieved.

• 500 Internal Server Error – Fail to retrieve question.

Example Response

{
   "/api/question/1":{
      "content":[
         {
            "id":1,
            "content":"What is the domain of your IoT system ?"
         }
      ],
      "status":200
   }
}

Get Questions Answers

GET /api/questions/answers

Synopsis

Get the list of answers mapped to questions

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• question_id (int) – The id of the question.

• question_content (string) – The question content.

• answer_id (int) – The id of que answer mapped to that question.

• answer_content (string) – The answer content.

• question_answer_id – The relation id between question and answer.

• status (int) – Status code.

Status Codes

• 200 OK – Questions answers successfully retrieved.

• 500 Internal Server Error – Fail to retrieve questions answers.

Example Response

{
   "/api/questions/answers":{
      "content":[
         {
            "question_id":1
            "question_content":"What is the domain of your IoT system ?",
            "answer_id":1,
            "answer_content":"Smart home",
            "question_answer_id":1,
         },
         {
            "question_id":1
            "question_content":"What is the domain of your IoT system ?",
            "answer_id":2,
            "answer_content":"Smart Healthcare",
            "question_answer_id":2,
         }
      ],
      "status":200
   }
}

---

GET /api/question/(int: id)/answers

Synopsis

Get the list of answers mapped to question identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – id of the question.

Response JSON Object

• question_id (int) – The id of the question.

• question_content (string) – The question content.

• answer_id (int) – The id of que answer mapped to that question.

• answer_content (string) – The answer content.

• question_answer_id – The relation id between question and answer.

• status (int) – Status code.

Status Codes

• 200 OK – Question answers successfully retrieved.

• 500 Internal Server Error – Fail to retrieve question answers.

Example Response

{
   "/api/question/1/answers":{
      "content":[
         {
            "question_id":1,
            "question_content":"What is the domain of your IoT system ?",
            "answer_id":1,
            "answer_content":"Smart home",
            "question_answer_id":1
         },
         {
            "question_id":1,
            "question_content":"What is the domain of your IoT system ?",
            "answer_id":2,
            "answer_content":"Smart Healthcare",
            "question_answer_id":2
         }
      ],
      "status":200
   }
}

Add Question

POST /api/question

Synopsis

Add a new question.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• content (string) – The question content.

• description (string) – The question description.

Response JSON Object

• id (int) – The id of the new question.

• status (string) – Status code.

Status Codes

• 200 OK – Question successfully added.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to add question.

Example Request

{
   "content":"Test Question",
   "description":"Test question description",
}

Example Response

{"/api/question":{"id":1, "status":200}}

Edit Question

PUT /api/question

Synopsis

Update a question identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• id (int) – The id of the question to update.

• content (string) – The question content.

• description (string) – The question description.

Response JSON Object

• status (string) – Status code.

Status Codes

• 200 OK – Question successfully updated.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to update question.

Example Request

{
   "id": 1,
   "content":"Test Question Updated",
   "description":"Test question description updated",
}

Example Response

{"/api/question":{"status":200}}

Remove Question

DELETE /api/question/(int: id)

Synopsis

Removes a question identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the question to remove.

Response JSON Object

• status (string) – Status code.

Status Codes

• 200 OK – Question successfully removed.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to remove question.

Example Response

{"/api/question":{"status":200}}

Answers Services API

This section includes details concerning services developed for the answer entity implemented in

answer.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
from api import app, mysql
from flask import request
import modules.error_handlers, modules.utils # SAM's modules
import views.user, views.question # SAM's views

"""
[Summary]: Adds a new question to the database.
[Returns]: Response result.
"""
@app.route('/api/answer', methods=['POST'])
def add_answer():
    DEBUG=True
    if request.method != 'POST': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"content", "description"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    

    content     = json_data['content']
    description = json_data['description']
    createdon   = "createdon" in json_data and json_data['createdon'] or None
    updatedon   = "updatedon" in json_data and json_data['updatedon'] or None
    
    # Build the SQL instruction using our handy function to build sql instructions.
    values = (content, description, createdon, updatedon)
    sql, values = modules.utils.build_sql_instruction("INSERT INTO answer", ["content", "description", createdon and "createdon" or None, updatedon and "updatedon" or None], values)
    if (DEBUG): print("[SAM-API]: [POST]/api/answer - " + sql)

    # Add
    n_id = modules.utils.db_execute_update_insert(mysql, sql, values)
    if (n_id is None):
        return(modules.utils.build_response_json(request.path, 400))  
    else:
        return(modules.utils.build_response_json(request.path, 200, {"id": n_id}))


"""
[Summary]: Delete an answer.
[Returns]: Returns a success or error response
"""
@app.route('/api/answer/<ID>', methods=["DELETE"])
def delete_answer(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'DELETE': return
    
    # 1. Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # 2. Connect to the database and delete the resource
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM answer WHERE ID=%s", ID)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 3. The Delete request was a success, the user 'took the blue pill'.
    if (not internal_call):
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)

"""
[Summary]: Updates a question.
[Returns]: Response result.
"""
@app.route('/api/answer', methods=['PUT'])
def update_answer():
    DEBUG=True
    if request.method != 'PUT': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"id"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    

    content     = "content"     in json_data and json_data['content'] or None
    description = "description" in json_data and json_data['description'] or None
    createdon   = "createdon"   in json_data and json_data['createdon'] or None
    updatedon   = "updatedon"   in json_data and json_data['updatedon'] or None

    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Build the SQL instruction using our handy function to build sql instructions.
    values  = (content, description, createdon, updatedon)
    columns = [content and "content" or None, description and "description" or None, createdon and "createdon" or None, updatedon and "updatedOn" or None]
    where   = "WHERE id="+str(json_data['id'])
    # Check if there is anything to update (i.e. frontend developer has not sent any values to update).
    if (len(values) == 0): return(modules.utils.build_response_json(request.path, 200))   

    sql, values = modules.utils.build_sql_instruction("UPDATE answer", columns, values, where)
    if (DEBUG): print("[SAM-API]: [PUT]/api/answer - " + sql + " " + str(values))

    # Update Recommendation
    modules.utils.db_execute_update_insert(mysql, sql, values)

    return(modules.utils.build_response_json(request.path, 200))   


"""
[Summary]: Get Answers.
[Returns]: Response result.
"""
@app.route('/api/answers')
def get_answers():
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, content, description, createdon, updatedon FROM answer")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['content']     = row[1]
            data['description'] = row[2]
            data['questions']   = find_questions_of_answer(row[0])
            data['createdon']   = row[3]
            data['updatedon']   = row[4]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas))

"""
[Summary]: Finds the list of questions linked to an answer.
[Returns]: A list of questions or an empty array if None are found.
"""
def find_questions_of_answer(answer_id):
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT questionID FROM question_answer WHERE answerID=%s", answer_id)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return([]) 
       
    else:
        questions = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            question = views.question.find_question(row[0], True)[0]
            questions.append(question)
        cursor.close()
        conn.close()
       
        # 'May the Force be with you, young master'.
        return(questions)


"""
[Summary]: Finds Answer.
[Returns]: Response result.
"""
@app.route('/api/answer/<ID>', methods=['GET'])
def find_answer(ID, internal_call=False):
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # 2. Let's get the answeers for the question from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, content, description, createdon, updatedon FROM answer WHERE ID=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['content']     = row[1]
            data['description'] = row[2]
            data['createdon']   = row[3]
            data['updatedon']   = row[4]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        return(modules.utils.build_response_json(request.path, 200, datas)) 

Get Answers

GET /api/answers

Synopsis

Get the list of answers mapped to questions.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – The id of the answer or question mapped to the current answer.

• content (string) – The answer or question content.

• description (string) – Description of the answer.

• questions (array) – Array of questions mapped to the current answer.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Answers successfully retrieved.

• 500 Internal Server Error – Fail to retrieve answers.

Example Response

{
   "/api/answers":{
      "content":[
         {
            "id":1,
            "content":"Smart home",
            "description":"Smart home description",
            "questions":[
               {
                  "id":1,
                  "content":"What is the domain of your IoT system ?"
               }
            ],
            "createdon":"Fri, 19 Nov 2021 15:29:18 GMT",
            "updatedon":"Fri, 19 Nov 2021 15:29:18 GMT"
         },
         {
            "id":2,
            "content":"Smart Healthcare",
            "description":"Smart healthcare description",
            "questions":[
               {
                  "id":1,
                  "content":"What is the domain of your IoT system ?"
               }
            ],
            "createdon":"Fri, 19 Nov 2021 15:29:18 GMT",
            "updatedon":"Fri, 19 Nov 2021 15:29:18 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/answers/(int: id)

Synopsis

Get an answer identify by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – The id of the answer.

• content (string) – The answer content.

• description (string) – Description of the answer.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Answers successfully retrieved.

• 500 Internal Server Error – Fail to retrieve answers.

Example Response

{
   "/api/answer/1":{
      "content":[
         {
            "id":1,
            "content":"Smart home",
            "description":"Smart home description",
            "createdon":"Fri, 19 Nov 2021 15:29:18 GMT",
            "updatedon":"Fri, 19 Nov 2021 15:29:18 GMT"
         }
      ],
      "status":200
   }
}

Add Answer

POST /api/answer

Synopsis

Add a new answer.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• content (string) – The answer content.

• description (string) – The answer description.

Response JSON Object

• id (int) – The id of the new answer.

• status (string) – Status code.

Status Codes

• 200 OK – Answer successfully added.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to add answer.

Example Request

{
        "content":"Test Answer",
        "description":"Test answer description"
}

Example Response

{"/api/answer":{"id":4, "status":200}}

Edit Answer

PUT /api/answer

Synopsis

Update an answer identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• id (int) – The id of the answer to update.

• content (string) – The answer content.

• description (string) – The answer description.

Response JSON Object

• status (string) – Status code.

Status Codes

• 200 OK – Answer successfully updated.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to update answer.

Example Request

{
   "id":1,
   "content":"Test Answer Updated",
   "description":"Test answer description updated"
}

Example Response

{"/api/answer":{"status":200}}

Remove Answer

DELETE /api/answer/(int: id)

Synopsis

Removes a answer identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the answer to remove.

Response JSON Object

• status (string) – Status code.

Status Codes

• 200 OK – Answer successfully removed.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to answer question.

Example Response

{"/api/answer":{"status":200}}

Recommendations Services API

This section includes details concerning services developed for the recommendation entity implemented in

recommendation.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
from api import app, mysql
from flask import request
import os
import modules.error_handlers, modules.utils # SAM's modules
import views.user, views.module # SAM's views


"""
[Summary]: Adds a new recommendation to the database.
[Returns]: Response result.
"""
@app.route('/api/recommendation', methods=['POST'])
def add_recommendation(internal_json=None):
    DEBUG=False
    if (internal_json is None):
        if (request.method != 'POST'): return
    
    # Check if the user has permissions to access this resource
    if (internal_json is None): views.user.isAuthenticated(request)
   
    if (internal_json is None):
        json_data = request.get_json()
    else:
        json_data = internal_json

    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): 
        if (internal_json is None):
            return(modules.utils.build_response_json(request.path, 400)) 
        else:
            return(None)
    
    # Validate if the necessary data is on the provided JSON
    # Check if the recommendation [id] is null. If not null, it means the recommendation was previsoulyed added and we just need to add the question_answers mapping to table [recommendation_question_answer].
    if (json_data['id'] is None):
        if (not modules.utils.valid_json(json_data, {"content"})):
            raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    
        
        content         = json_data['content']
        description     = "description" in json_data and json_data['description']     or None
        guide           = "guide"     in json_data and json_data['guide']     or None
        createdon       = "createdon" in json_data and json_data['createdon'] or None
        updatedon       = "updatedon" in json_data and json_data['updatedon'] or None
    
        # Build the SQL instruction using our handy function to build sql instructions.
        values = (content, description, guide, createdon, updatedon)
        sql, values = modules.utils.build_sql_instruction("INSERT INTO recommendation", ["content", description and "description" or None, guide and "guidefilename" or None, createdon and "createdon" or None, updatedon and "updatedon" or None], values)
        if (DEBUG): print("[SAM-API]: [POST]/recomendation - " + sql + " " + str(values))

        # Add
        recommendation_id = modules.utils.db_execute_update_insert(mysql, sql, values)
        if (recommendation_id is None): 
            if (internal_json is None):
                return(modules.utils.build_response_json(request.path, 400))  
            else:
                return("None")
        
        # If availabe, set the final guide filename after knowing the database id of the new recommendation
        if guide and recommendation_id:
            # Get the file extension of the guide uploaded (it can be txt or md) in order to create the final name of the file.
            file_extension = guide[guide.rfind("."): len(guide)]
            final_recommendation_filename = "recommendation_" + str(recommendation_id) + file_extension
            sql, values = modules.utils.build_sql_instruction("UPDATE recommendation", ["guideFileName"], final_recommendation_filename, "WHERE id="+str(recommendation_id))
            modules.utils.db_execute_update_insert(mysql, sql, values, True)
        
    else:
        recommendation_id = json_data['id']
 


    # This recommendation is given if a question answer association is defined.
    # question_answer_id is a column in table "Recommendation_Question_Answer"
    questions_answers = "questions_answers" in json_data and json_data['questions_answers'] or None
    if (questions_answers is None): 
        if (internal_json is None):
            return(modules.utils.build_response_json(request.path, 200, {"id": recommendation_id}))   
        else:
            return({"id": recommendation_id})
    
    # Build the SQL instruction using our handy function to build sql instructions.
    for question_answer in questions_answers: 
        question_answer_id = question_answer['id']
        columns = ["recommendationID", "questionAnswerID"] 
        values  = (recommendation_id, question_answer_id)
        sql, values = modules.utils.build_sql_instruction("INSERT INTO recommendation_question_answer", columns, values)
        if (DEBUG): print("[SAM-API]: [POST]/recomendation - " + sql + " " + str(values))
        # Add
        rqa_id = modules.utils.db_execute_update_insert(mysql, sql, values)

    if (rqa_id is None):
        if (internal_json is None):
            return(modules.utils.build_response_json(request.path, 400))
        else:
            return(None)
    else:
        if (internal_json is None):
            return(modules.utils.build_response_json(request.path, 200, {"id": recommendation_id}))   
        else:
            return({"id", recommendation_id})

"""
[Summary]: Delete a recommendation.
[Returns]: Returns a success or error response
"""
@app.route('/api/recommendation/<recommendation_id>', methods=["DELETE"])
def delete_recommendation(recommendation_id):
    if request.method != 'DELETE': return
    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)
    
    # 2. If any, get the filename of the guide linked to the recommendation.
    recommendation_guide = find_recommendation(recommendation_id, True)[0]['guide']

    # 3. Connect to the database and delete the resource
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM recommendation WHERE ID=%s", recommendation_id)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()
        # 3.1. If guide available, remove the file from the server.
        if (recommendation_guide): 
            try:
                os.remove(os.path.join(views.file.UPLOAD_DIRECTORY, recommendation_guide))
            except Exception as e:
                pass # For some reason, the file may not exist.

    # 4. The Delete request was a success, the user 'took the blue pill'.
    return (modules.utils.build_response_json(request.path, 200))

"""
[Summary]: Updates a recommendation
[Returns]: Response result.
"""
@app.route('/api/recommendation', methods=['PUT'])
def update_recommendation():
    DEBUG=False
    if request.method != 'PUT': return
    # Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    json_data = request.get_json()
    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # Validate if the necessary data is on the provided JSON 
    if (not modules.utils.valid_json(json_data, {"id"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)    

    content     = "content"     in json_data and json_data['content'] or None
    description = "description" in json_data and json_data['description'] or None
    guide       = "guide"       in json_data and json_data['guide']     or None
    createdon   = "createdon"   in json_data and json_data['createdon'] or None
    updatedon   = "updatedon"   in json_data and json_data['updatedon'] or None

    # If the mimetype does not indicate JSON (application/json, see is_json()), this returns None.
    if (json_data is None): return(modules.utils.build_response_json(request.path, 400)) 

    # If availabe, set the final guide filename after knowing the database id of the new recommendation

    if guide and json_data['id']:
        # Remove previous guide.
        previous_guide = find_recommendation(json_data['id'], True)[0]['guide']
        if (guide != previous_guide): 
            os.remove(os.path.join(views.file.UPLOAD_DIRECTORY, previous_guide))

        # Get the file extension of the guide uploaded (it can be txt or md) in order to create the final name of the file.
        file_extension = guide[guide.rfind("."): len(guide)]
        final_recommendation_filename = "recommendation_" + str(json_data['id']) + file_extension
        guide = final_recommendation_filename

    # Build the SQL instruction using our handy function to build sql instructions.
    values  = (content, description, guide, createdon, updatedon)
    columns = [content and "content" or None, description and "description" or None, guide and "guideFileName" or None, createdon and "createdon" or None, updatedon and "updatedOn" or None]
    where   = "WHERE id="+str(json_data['id'])
    # Check if there is anything to update (i.e. frontend developer has not sent any values to update).
    if (len(values) == 0): return(modules.utils.build_response_json(request.path, 200))   

    sql, values = modules.utils.build_sql_instruction("UPDATE recommendation", columns, values, where)
    if (DEBUG): print("[SAM-API]: [PUT]/recomendation - " + sql + " " + str(values))

    # Update Recommendation
    modules.utils.db_execute_update_insert(mysql, sql, values)

    return(modules.utils.build_response_json(request.path, 200))   

"""
[Summary]: Get recommendations.
[Returns]: Response result.
"""
@app.route('/api/recommendations', methods=['GET'])
def get_recommendations(internal_call=False):
    if (not internal_call): 
        if request.method != 'GET': return
    # 1. Check if the user has permissions to access this resource
    if (not internal_call): 
        views.user.isAuthenticated(request)

    # 2. Let's get the set of available recommendations
    recommendations = []
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, content, description, guideFileName, createdon, updatedon FROM recommendation")
        res = cursor.fetchall()
        for row in res:
            recommendation = {}
            recommendation['id']          = row[0]
            recommendation['content']     = row[1]
            recommendation['description'] = row[2]
            recommendation['guide']       = row[3]
            recommendation['createdOn']   = row[4]
            recommendation['updatedOn']   = row[5]
            recommendation['modules']     = []
            recommendations.append(recommendation)
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:

        # 3. Let's get the info about the modules linked to each recommendation.
        cursor.close()
        for recommendation in recommendations:
            try:
                cursor  = conn.cursor()
                cursor.execute("SELECT module_id FROM view_module_recommendations WHERE recommendation_id=%s", recommendation['id'])
                res = cursor.fetchall()
                for row in res:
                    module = views.module.find_module(row[0], True)[0]
                    # Remove unnecessary information from the object
                    if ("tree" in module): del module['tree']
                    if ("recommendations" in module): del module['recommendations']
                    if ("dependencies" in module): del module['dependencies']
                    recommendation['modules'].append(module)
            except Exception as e:
                raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
            cursor.close()
        
        conn.close()
        # 4. The request was a success, the user 'is in the rabbit hole'
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, recommendations))
        else:
            return(recommendations)

"""
[Summary]: Finds recommendation by ID.
[Returns]: Response result.
"""
@app.route('/api/recommendation/<ID>', methods=['GET'])
def find_recommendation(ID, internal_call=False):
    if (not internal_call): 
        if request.method != 'GET': return
    # 1. Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # 2. Let's get the set of available recommendations
    results = []
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, content, description, guideFileName, createdon, updatedon FROM recommendation WHERE ID=%s", ID)
        res = cursor.fetchall()
        for row in res:
            result = {}
            result['id']          = row[0]
            result['content']     = row[1]
            result['description'] = row[2]
            result['guide']       = row[3]
            result['createdOn']   = row[4]
            result['updatedOn']   = row[5]
            results.append(result)
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()
        
        # 3. The request was a success, the user 'is in the rabbit hole'
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, results)) 
        else:
            return(results)
"""
[Summary]: Finds the recommendations of question, answer association.
[Returns]: Response result.
"""
@app.route('/api/recommendations/question/<question_id>/answer/<answer_id>', methods=['GET'])
def find_recommendations_of_question_answer(question_id, answer_id, internal_call=False):
    if request.method != 'GET': return
    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)
    
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT recommendation_id as id, content, description, guide, createdon, updatedon FROM view_question_answer_recommendation WHERE question_id = %s AND answer_id = %s", (question_id, answer_id))
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 

    # 2.2. Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(None)    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['content']     = row[1]
            data['description'] = row[2]
            data['guide']       = row[3] 
            data['type']        = "recommendation"
            data['children']    = []
            data['createdon']   = row[4]
            data['updatedon']   = row[5]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you, young master'.
        if (internal_call):
            return(datas)
        else:
            return(modules.utils.build_response_json(request.path, 200, datas)) 

"""
[Summary]: Finds the recommendations of a module
[Returns]: Response result.
"""
@app.route('/api/recommendations/module/<module_id>', methods=['GET'])
def find_recommendations_of_module(module_id, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': 
            return
    
    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)
    
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT recommendation_ID, recommendation_content, createdon, updatedon FROM view_module_recommendations WHERE module_id=%s", module_id)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 

    # Check for empty results 
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(None)    
    else:
        recommendations = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            recommendation = {}
            recommendation['id']                  = row[0]
            recommendation['content']             = row[1]
            recommendation['createdon']           = row[2]
            recommendation['updatedon']           = row[3]
            recommendations.append(recommendation)
    
    # Find questions and answers associated or mapped to a particular recommendation and module
    for recommendation in recommendations:
        recommendation_id = recommendation['id']
        try:
            cursor  = conn.cursor()
            cursor.execute("SELECT recommendation_question_answer_id, question_id, answer_id, createdon, updatedon FROM view_module_recommendations_questions_answers WHERE module_id=%s and recommendation_id=%s", (module_id, recommendation_id))
            res = cursor.fetchall()
        except Exception as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500)
        if (len(res) != 0):
            questions_answers = []
            for row in res:
                question_answer = {}
                question_answer['id']          = row[0]
                question_answer['question_id'] = row[1]
                question_answer['answer_id']   = row[2]
                question_answer['createdon']   = row[3]
                question_answer['updatedon']   = row[4]
                questions_answers.append(question_answer)
            cursor.close()
            recommendation['questions_answers'] = questions_answers
    
    # 'May the Force be with you, young master'.
    conn.close()
    if (internal_call):
        return(recommendations)
    else:
        return(modules.utils.build_response_json(request.path, 200, recommendations)) 


"""
[Summary]: Removes the mapping between a module and its recommendations.
[Returns]: Returns a reponse object.
"""
@app.route('/api/recommendations/module/<module_id>', methods=['DELETE'])
def remove_recommendations_of_module(module_id, internal_call=False):
    if not internal_call:
        if request.method != 'DELETE': return

    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)
   
    # 2. Connect to the database and delete the resource
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM recommendation_question_answer WHERE ID IN (SELECT recommendation_question_answer_ID From view_module_recommendations_questions_answers where module_id=%s);", module_id)
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()
    
    # The Delete request was a success, the user 'took the blue pill'.
    if (not internal_call):
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)


"""
[Summary]: Removes the mapping of a module and a recommendation.
[Returns]: Returns a reponse object.
"""
@app.route('/api/recommendation/<recommendation_id>/module/<module_id>', methods=['DELETE'])
def remove_recommendation_of_module(recommendation_id, module_id, internal_call=False):
    if not internal_call:
        if request.method != 'DELETE': return

    # Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)
   
    # 2. Connect to the database and delete the resource
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("DELETE FROM recommendation_question_answer WHERE ID IN (SELECT recommendation_question_answer_ID From view_module_recommendations_questions_answers where module_id=%s AND recommendation_id=%s);", (module_id, recommendation_id))
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()
    
    # The Delete request was a success, the user 'took the blue pill'.
    if (not internal_call):
        return (modules.utils.build_response_json(request.path, 200))
    else:
        return(True)

Get Recommendations

GET /api/recommendations

Synopsis

Get recommendations.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Id of the recommendation.

• content (string) – Recommendation name.

• description (string) – Description of the recommendation.

• guide (string) – The filename of the recommendation guide.

• modules (array) – Array of modules mapped to the current recommendation.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Recommendations successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve recommendations.

Example Response

{
   "/api/recommendations":{
      "content":[
         {
            "id":1,
            "content":"Confidentiality",
            "description":null,
            "guide":null,
            "modules":[
               {
                  "id":1,
                  "shortname":"SRE",
                  "displayname":"Security Requirements",
                  "fullname":"Security Requirements Elicitation",
                  "description":"test",
                  "avatar":null,
                  "logic_filename":null,
                  "type_id":null,
                  "createdon":"Sat, 20 Nov 2021 13:29:49 GMT",
                  "updatedon":"Sat, 20 Nov 2021 13:29:49 GMT"
               }
            ],
            "createdOn":"Sat, 20 Nov 2021 13:29:49 GMT",
            "updatedOn":"Sat, 20 Nov 2021 13:29:49 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/recommendation/(int: id)

Synopsis

Get recommendation identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Form Parameters

• id – The id of the recommendation.

Response JSON Object

• id (int) – Id of the recommendation.

• content (string) – Recommendation name.

• description (string) – Description of the recommendation.

• guide (string) – The filename of the recommendation guide.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Recommendation successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve recommendation.

Example Response

{
   "/api/recommendation/1":{
      "content":[
         {
            "id":1,
            "content":"Confidentiality",
            "description":null,
            "guide":null,
            "createdOn":"Sat, 20 Nov 2021 13:29:49 GMT",
            "updatedOn":"Sat, 20 Nov 2021 13:29:49 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/recommendations/module/(int: id)

Synopsis

Finds the set of recommendations for a module identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Form Parameters

• id – The id of the module.

Response JSON Object

• id (int) – Id of the recommendation.

• content (string) – Recommendation name.

• questions_answers (array) – An array that contains the mapping between questions and answers for the current recommendation and module.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Recommendations successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve recommendations.

Example Response

{
   "/api/recommendations/module/1":{
      "content":[
         {
            "id":1,
            "content":"Confidentiality",
            "questions_answers":[
               {
                  "question_id":1,
                  "answer_id":1,
                  "createdon":"Sat, 20 Nov 2021 13:29:49 GMT",
                  "updatedon":"Sat, 20 Nov 2021 13:29:49 GMT"
               }
            ],
            "createdon":"Sat, 20 Nov 2021 13:29:49 GMT",
            "updatedon":"Sat, 20 Nov 2021 13:29:49 GMT"
         }
      ],
      "status":200
   }
}

Note

In this example, for module 1 the recommendation 1 is given if for question_id the answer_id is given by a user.

---

Add Recommendation

POST /api/recommendation

Synopsis

Add a new recommendation.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• content (string) – The name of the new recommendation.

• description (string) – The description of the new recommendation.

• guide (string) – The filename of the recommendation guide.

• questions_answers (array) – An array that contains the mapping between questions and answers for the new recommendation.

Response JSON Object

• id (int) – The id of the new recommendation.

• status (int) – Status code.

Status Codes

• 200 OK – Recommendation successfully added.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to add recommendation.

Example Request

{
   "content":"New Recommendation",
   "description":"New Recommendation Description",
   "guide":"new_recommendation.md",
   "questions_answers":[
      {
         "question_id":1,
         "answer_id":1
      }
   ]
}

Important

In order to upload a guide for the new recommendation you need to use this service in conjunction with the service detailed in /api/file/(string:filename).

Example Response

{"/api/recommendation":{"id":4, "status":200}}

Edit Recommendation

PUT /api/recommendation

Synopsis

Update a recommendation identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• id (string) – The id of the recommendation to update.

• content (string) – The name of the new recommendation.

• description (string) – The description of the new recommendation.

• guide (string) – The filename of the recommendation guide.

Response JSON Object

• status (int) – Status code.

Status Codes

• 200 OK – Recommendation successfully updated.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to update recommendation.

Example Request

{
   "id":4,
   "content":"New Recommendation updated",
   "description":"New recommendation description updated",
   "guide":"recommendation_updated_guide.md"
}

Important

In order to upload a new guide you need to use this service in conjunction with the service detailed in /api/file/(string:filename).

Example Response

{"/api/recommendation":{"status":200}}

Remove Recommendation

DELETE /api/recommendations/(int: id)

Synopsis

Remove a recommendation identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Form Parameters

• id – The id of the recommendation to remove.

Response JSON Object

• status (int) – Status code.

Status Codes

• 200 OK – Recommendation successfully removed.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to remove recommendation.

Example Response

{"/api/recommendation":{"status":200}}

---

DELETE /api/recommendations/module/(int: id)

Synopsis

Removes the mapping between a module identified by id and its recommendations.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Form Parameters

• id – The id of the module.

Response JSON Object

• status (int) – Status code.

Status Codes

• 200 OK – Mapping successfully removed.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to remove mapping.

Example Response

{"/api/recommendations/modules/1":{"status":200}}

---

DELETE /api/recommendations/(int: id)/module/(int: id)

Synopsis

Removes the mapping between a module id and a recommendation id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Form Parameters

• id – The id of the recommendation or module.

Response JSON Object

• status (int) – Status code.

Status Codes

• 200 OK – Mapping successfully removed.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to remove mapping.

Example Response

{"/api/recommendations/1/modules/1":{"status":200}}

Sessions Services API

This section includes details concerning services developed for the session entity implemented in

session.py.

"""
// ---------------------------------------------------------------------------
//
//	Security Advising Modules (SAM) for Cloud IoT and Mobile Ecosystem
//
//  Copyright (C) 2020 Instituto de Telecomunicações (www.it.pt)
//  Copyright (C) 2020 Universidade da Beira Interior (www.ubi.pt)
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
// 
//  This work was performed under the scope of Project SECURIoTESIGN with funding 
//  from FCT/COMPETE/FEDER (Projects with reference numbers UID/EEA/50008/2013 and 
//  POCI-01-0145-FEDER-030657) 
// ---------------------------------------------------------------------------
"""
import shutil
from api import app, mysql
from flask import request
import json, os
import modules.error_handlers, modules.utils # SAM's modules
import views.user, views.module, views.dependency # SAM's views

"""
[Summary]: Adds a new session to a user.
[Returns]: Response result.
"""
@app.route('/api/session', methods=['POST'])
def add_session():
    DEBUG = False
    if request.method != 'POST': return
    data = {}

    # 1. Check if the user has permissions to access this resource.
    views.user.isAuthenticated(request)

    # 2. Let's get our shiny new JSON object
    #    Always start by validating the structure of the json, if not valid send an invalid response.
    try:
        obj = request.json
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 
    
    # 3. Let's validate the data of our JSON object with a custom function.
    if (not modules.utils.valid_json(obj, {"email", "module_id"})):
        raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)

    # 4. Before starting a new session, let's just check if there are any dependencies. That is if the user needs to answer questions from any other module before the current one.
    module_dependencies = views.module.find_module(obj['module_id'], True)[0]['dependencies']
    
    if (DEBUG): modules.utils.console_log("['POST']/api/session", "List of dependencies for module " + str(obj['module_id']) + "=" + str(module_dependencies))
    if (len(module_dependencies) != 0):
        # 4.1. Let's iterate the list of dependencies and check if the user answered the questions to that module (i.e., a closed session exists)
        for module_dependency in module_dependencies:
            dep_module_id = module_dependency['module']['id']
            user_id = views.user.find_user(obj['email'], True)['id']

            # 4.2. Let's get the sesions of the current user for the dependency
            user_sessions = count_sessions_of_user_module(dep_module_id, user_id)
            if (user_sessions == 0):
                data = {}
                data['message']      = "A session was not created, the module dependencies are not fulfilled, the module is dependent on one or more modules."
                data['dependencies'] = module_dependencies
                return (modules.utils.build_response_json(request.path, 404, data))


    # 5. Check if there is an identical session closed, 
    #    if true, notify the user on the return response object that a new session will be created; otherwise, 
    #    delete all that of the previously opened session.
    destroySessionID = -1
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, ended FROM session WHERE userID=(SELECT ID FROM user WHERE email=%s) AND moduleID=%s ORDER BY ID DESC LIMIT 1", (obj['email'], obj['module_id']))
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)

    if (len(res) != 0):
        for row in res:
            if (row[1] == 1):
                data['message'] = "A session for this module was previously created and closed, a new one will be created."
            else:
                destroySessionID = int(row[0])
                data['message'] = "A session for this module was previously created, but it is still open. The session will be deleted and recreated."
    cursor.close()

    if (destroySessionID != -1):
        try:
            conn    = mysql.connect()
            cursor  = conn.cursor()
            cursor.execute("DELETE FROM session WHERE ID=%s", destroySessionID)
            conn.commit()
        except Exception as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
        finally:
            cursor.close()

    
    # 6. Connect to the database and add a new session.
    try:
        cursor  = conn.cursor()
        cursor.execute("INSERT INTO session (userID, moduleID) VALUES ((SELECT ID FROM user WHERE email=%s), %s)", (obj['email'],obj['module_id']))
        data['id'] = conn.insert_id()
        conn.commit()

    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    data['module'] = views.module.find_module(obj['module_id'], True)

    # 7. The request was a success, the user 'took the blue pill'.
    return (modules.utils.build_response_json(request.path, 200, data))

"""
[Summary]: Updates the session with the set of answers given and the corresponding questions.
[Returns]: Response result.
"""
@app.route('/api/session/<ID>', methods=['PUT'])
def update_session(ID):
    if request.method != 'PUT': return
    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's get our shiny new JSON object.
    # - Always start by validating the structure of the json, if not valid send an invalid response.
    try:
        obj = request.json
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 400) 
    
    # print(obj)
    answer_user_inputted = False
    # 3. Let's validate the data of our JSON object with a custom function.
    if (not modules.utils.valid_json(obj, {"question_id","answer_id"})):
        if (modules.utils.valid_json(obj, {"question_id","input"})): 
            answer_user_inputted = True
        else:
            raise modules.error_handlers.BadRequest(request.path, "Some required key or value is missing from the JSON object", 400)

    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        if (not answer_user_inputted):
            cursor.execute("INSERT INTO session_user_answer (sessionID, questionAnswerID) VALUES (%s, (SELECT ID FROM question_answer WHERE questionID=%s AND answerID=%s))", (ID, obj['question_id'], obj['answer_id']))
        else:
            cursor.execute("INSERT INTO session_user_answer (sessionID, questionID, input) VALUES (%s, %s, %s)", (ID, obj['question_id'], obj['input']))
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # 5. The Update request was a success, the user 'is in the rabbit hole'
    return (modules.utils.build_response_json(request.path, 200))


"""
[Summary]: Get sessions (opened and closed)
[Returns]: Returns response result.
"""
@app.route('/api/sessions', methods=['GET'])
def get_sessions():
    if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    views.user.isAuthenticated(request)

    # 2. Let's existing sessions from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, userID, moduleID, ended, createdOn, updatedOn FROM session")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.1. Check for empty results.
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))    
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['user_id']     = row[1]
            data['module_id']   = row[2]
            data['ended']       = row[3]
            data['createdOn']   = row[4]
            data['updatedOn']   = row[5]
            datas.append(data)
        cursor.close()
        conn.close()
        # 3. 'May the Force be with you'.
        return(modules.utils.build_response_json(request.path, 200, datas))    

"""
[Summary]: Ends a user's session.
[Returns]: Response result.
"""
@app.route('/api/session/<ID>/end', methods=['PUT'])
def end_session(ID):
    if request.method != 'PUT': return

    # 1. Check if the user has permissions to access this resource.
    views.user.isAuthenticated(request)

    # 2. End a session by defining the flag ended to one.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("UPDATE session SET ended=1 WHERE ID=%s", ID) 
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()
        # 3. The request was a success, let's generate the recommendations.
        return find_recommendations(request, ID)

"""
[Summary]: Gets a session that was previsouly closed. A session is considered closed when all answers were given by the end user.
[Returns]: Response result.
"""
@app.route('/api/session/<ID>/closed', methods=['GET'])
def find_session_closed(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return
    
    # 0. Check if the user has permissions to access this resource.
    if (not internal_call): views.user.isAuthenticated(request)

    # 1. Let's get the data of the session that has ended.
    print("getting data of the session that has ended.") 
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT session_ID, session_userID, session_moduleID, session_ended, session_createdOn, session_updatedOn, question_ID, question, answer_input, module_logic, answer_id, answer FROM view_session_answers WHERE session_ID=%s AND session_ended=1 ORDER BY question_ID", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2. Check for empty results.
    print("Checking emoty results")
    if (len(res) == 0):
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, userID, moduleID, ended, createdOn, updatedOn FROM session WHERE ID = %s" , ID)
        res = cursor.fetchall()
        data = {}
        # 3. Let's get the info about the session.
        for row in res:
            data['id']           = row[0]
            data['user_id']       = row[1]
            data['module_id']     = row[2]
            # data['module_logic'] = row[9] 
            data['ended']        = row[3]
            data['createdOn']    = row[4]
            data['updatedOn']    = row[5]
            break

        try:
            cursor  = conn.cursor()
            cursor.execute("SELECT recommendation_id, recommendation, recommendation_description, recommendation_guide  FROM view_session_recommendation WHERE session_id=%s", ID)
            res = cursor.fetchall()
        except Exception as e:
            raise modules.error_handlers.BadRequest(request.path, str(e), 500)

        if (len(res) != 0):
            recommendations = []
            for row in res:
                recommendation = {}
                recommendation['id']                  = row[0]
                recommendation['content']             = row[1]
                recommendation['description']         = row[2]
                recommendation['recommendation_guide'] = row[3]
                recommendations.append(recommendation)
            data.update({"recommendations": recommendations})
        conn.close()
        cursor.close()

        if (internal_call):
            return(data)
        else:
            return(modules.utils.build_response_json(request.path, 400))
    else:
        data = {}
        previous_question_id = 0 # To support multiple choice questions
        # 3. Let's get the info about the session.
        for row in res:
            data['id']           = row[0]
            data['user_id']       = row[1]
            data['module_id']     = row[2]
            # data['module_logic'] = row[9] 
            data['ended']        = row[3]
            data['createdOn']    = row[4]
            data['updatedOn']    = row[5]
            break
        # 4. Let's get the questions and inputted answers.
        questions = []
        for row in res:
            question = {}
            if previous_question_id == 0 or previous_question_id != row[6]:
                previous_question_id = row[6]
            else:
                continue
            question['id']           = row[6]
            question['content']      = row[7]

            answers = [] # Empty array of answers
            for row in res:
                if row[6] != question['id']:
                    continue
                # Let's check if the answer was user inputted, or selected from the database.
                if (row[8] != None):
                    answers.append({ "ID": -1, "content": row[8]})
                else:
                    answers.append({ "ID": row[10], "content": row[11]})
            
            question['answer'] = answers
            questions.append(question)
        data.update({"questions":  questions})
    cursor.close()
    
    # 5. Let's now get the recommendations, if any, stored for this session
    print("Getting recomendations stored")
    try:
        cursor  = conn.cursor()
        cursor.execute("SELECT recommendation_id, recommendation, recommendation_description, recommendation_guide  FROM view_session_recommendation WHERE session_id=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)

    if (len(res) != 0):
        recommendations = []
        for row in res:
            recommendation = {}
            recommendation['id']                  = row[0]
            recommendation['content']             = row[1]
            recommendation['description']         = row[2]
            recommendation['recommendation_guide'] = row[3]
            recommendations.append(recommendation)
        data.update({"recommendations": recommendations})
    conn.close()
    cursor.close()

    if (internal_call): 
        return(data) 
    else: 
        return(modules.utils.build_response_json(request.path, 200, data))


"""
[Summary]: Gets closed sessions. A session is considered closed when all answers were given by the end user.
[Returns]: Response result.
"""
@app.route('/api/sessions/closed', methods=['GET'])
def get_sessions_closed(internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return
    
    # Check if the user has permissions to access this resource.
    if (not internal_call): views.user.isAuthenticated(request)

    # Let's get the list of sessions from the db.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT id FROM session WHERE ended =1")
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results.
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (internal_call):
            return(None)
        else:
            return(modules.utils.build_response_json(request.path, 400))

    sessions = []
    for row in res:
        session = find_session_closed(row[0], True)
        if (session): sessions.append(session)
    cursor.close()
    conn.close()

    # 'May the Force be with you'.
    if (internal_call): 
        return(sessions) 
    else: 
        return(modules.utils.build_response_json(request.path, 200, sessions))


"""
[Summary]: Finds a session by ID (opened or closed)
[Returns]: Returns response result.
"""
@app.route('/api/session/<ID>', methods=['GET'])
def find_session(ID, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # 1. Check if the user has permissions to access this resource
    if (not internal_call): views.user.isAuthenticated(request)

    # 2. Let's existing sessions from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT ID, userID, moduleID, ended, createdOn, updatedOn FROM session WHERE ID=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # 2.1. Check for empty results.
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        # 2.2. Check if the session requested was ended.
        if (res[0][3] == 1):
            cursor.close()
            conn.close()
            datas = find_session_closed(ID, True)
            if (datas == None):
                if (not internal_call):
                    return(modules.utils.build_response_json(request.path, 404))
                else: 
                    return(None)
            else:
                if (not internal_call):
                    return(modules.utils.build_response_json(request.path, 200, datas)) 
                else:
                    return(datas)
        
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['user_id']     = row[1]
            data['module_id']   = row[2]
            data['ended']       = row[3]
            data['createdOn']   = row[4]
            data['updatedOn']   = row[5]
            datas.append(data)
        cursor.close()
        conn.close()

        # 3. 'May the Force be with you'.
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, datas))    
        else:
            return(datas)

"""
[Summary]: Finds sessions by user email (opened or closed)
[Returns]: Returns response result.
"""
@app.route('/api/sessions/user/<user_email>', methods=['GET'])
def find_sessions_of_user(user_email, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # Check if the user has permissions to access this resource
    if (not internal_call): 
        views.user.isAuthenticated(request)

    # Let's existing sessions from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT session_id, user_id, user_email, moduleID, ended, createdon, updatedon FROM view_user_sessions WHERE user_email=%s", user_email)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results.
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['user_id']     = row[1]
            data['user_email']  = row[2]
            data['ended']       = row[4]
            data['createdOn']   = row[5]
            data['updatedOn']   = row[6]
            session         = find_session_closed(data['id'], True)
            if session:
                if ("questions" in session): 
                    questions               = session['questions']
                    data['questions']       = questions
                if ("recommendations" in session):
                    recommendations         = session['recommendations']
                    data['recommendations'] = recommendations
            module = views.module.find_module(row[3], True)
            del module[0]['recommendations']
            del module[0]['tree']
            if (module): data['module'] = module[0]
            datas.append(data)
        cursor.close()
        conn.close()
        
        # 'May the Force be with you'.
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, datas))
        else:
            return(datas)

"""
[Summary]: Finds sessions by module ID and user email (closed)
[Returns]: Returns response result.
"""
@app.route('/api/sessions/module/<module_id>/user/<user_id>', methods=['GET'])
def find_sessions_of_user_module(module_id, user_id, internal_call=False):
    if (not internal_call):
        if request.method != 'GET': return

    # Check if the user has permissions to access this resource
    if (not internal_call): 
        views.user.isAuthenticated(request)

    # Let's existing sessions from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT session_id, user_id, user_email, moduleID, ended, createdon, updatedon FROM view_user_sessions WHERE moduleID=%s AND user_id=%s AND ended=1 ORDER BY session_id DESC", (module_id, user_id))
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
    
    # Check for empty results.
    if (len(res) == 0):
        cursor.close()
        conn.close()
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 404))
        else:
            return(None)
    else:
        datas = [] # Create a new nice empty array of dictionaries to be populated with data from the DB.
        for row in res:
            data = {}
            data['id']          = row[0]
            data['user_id']     = row[1]
            data['user_email']  = row[2]
            data['module_id']   = row[3]
            data['ended']       = row[4]
            data['createdOn']   = row[5]
            data['updatedOn']   = row[6]
            datas.append(data)
        cursor.close()
        conn.close()
        
        # 'May the Force be with you'.
        if (not internal_call):
            return(modules.utils.build_response_json(request.path, 200, datas))
        else:
            return(datas)

"""
[Summary]: After closing the session we need to find the recommendations based on the answers given on that session <ID>.
[Returns]: Response result.
"""
def find_recommendations(request, ID):
    # 1. Is there a logic file to process the set of answers given in this session? If yes, then, run the logic file. 
    #    This element will be in charge of calling the service to return one or more recommendations, depending on the implemented logic.  
    #    Otherwise, use the static information present in the database to infer the set of recommendations.
    session = (find_session_closed(ID, True))
    
    if (session is None):
        raise modules.error_handlers.BadRequest(request.path, "Unable to find recommendations for this session, maybe, there is something wrong with the answers given in this session.", 403) 

    module               = views.module.find_module(session['module_id'], True)
    tree                 = views.module.get_module_tree(str(session['module_id']), True)
    # Checks if tree exists
    if (tree != None):
        ordered_questions    = modules.utils.order_questions(tree, session['questions'], [])

    #if (session['module_logic'] != None):
    if (module[0]['logic_filename'] != None):
        try:
            # 2.1. Get information related to the current session. This includes the information about the module, the set of related questions, and the answers given by the user to those questions.
            json_session = json.loads(json.dumps(find_session(ID, True), indent=4, sort_keys=False, default=str))
            # Replace the questions with ordered questions
            # If questions exist
            if(tree != None):
                json_session['questions'] = ordered_questions
            # 2.2. Get the set of available recommendations.
            json_recommendations = json.loads(json.dumps(views.recommendation.get_recommendations(True), indent=4, sort_keys=False, default=str))
            
            # 2.3 Get dependencies of the current module, including the last sessions there were flagged has being closed.
            module_id   = json_session['module_id']
            user_id     = json_session['user_id']
            dependencies = views.dependency.find_dependency_of_module(module_id, True)

            if (dependencies):
                for dependency in dependencies:
                    del dependency['id']
                    del dependency['createdon']
                    del dependency['updatedon']
                    dep_module_id = dependency['module']['id']
                    # Get the last session of each dependency
                    last_session_id    = (find_sessions_of_user_module(dep_module_id, user_id, True)[0])['id']
                    # Get the answers given to that last session 
                    last_session = find_session(last_session_id, True)
                    dependency['module']['last_session'] = last_session
            
            json_session['dependencies'] =  json.loads(json.dumps(dependencies, indent=4, sort_keys=False, default=str))

            # 2.4. Dynamically load the logic element for the current session.
            module_logic_filename = module[0]['logic_filename']
            module_logic_filename = module_logic_filename[0: module_logic_filename.rfind('.')] # Remove file extension
            # name = "external." + module_logic_filename + "." + module_logic_filename
            mod = __import__('external.' + module_logic_filename, fromlist=[''])
            try:
                provided_recommendations = mod.run(json_session, json_recommendations)
            except Exception as e:
                modules.utils.console_log("logic_file", str(e))
                raise modules.error_handlers.BadRequest(request.path, str(e), 500)
                
            # 2.5. Make the recommendations taking into account the results of the logic element.
            if (len(provided_recommendations) != 0):
                for recommendation_id in provided_recommendations:
                    add_logic_session_recommendation(ID, recommendation_id)

        except Exception as e:
            modules.utils.console_log("end_session", str(e))
            raise modules.error_handlers.BadRequest(request.path, str(e), 500)

    # 2. Get the list of recommendations to be stored in the session.
    #    -> Some redundancy is expected to exist on the database, however, it avoids further 
    #       processing when checking the history of sessions.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        if (module[0]['logic_filename'] != None):
            table_name = "view_recommendation_logic"
        else:
            table_name = "view_recommendation"
        
        cursor.execute("SELECT session_id, recommendation_id, recommendation, recommendation_description, guideFileName FROM " + table_name + " WHERE session_id=%s", ID)
        res = cursor.fetchall()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)
        
    # 2.1 Check for empty results.
    if (len(res) == 0):
        cursor.close()
        conn.close()
        return(modules.utils.build_response_json(request.path, 404))
    
    result = {}
    recommendations = []
    result['recommendations'] = recommendations
    for row in res:
        if ("id" not in result): result['id']   = row[0]
        recommendation = {}
        recommendation['id']                    = row[1]
        recommendation['content']               = row[2]
        recommendation['description']           = row[3]
        recommendation['recommendation_guide']  = row[4]
        recommendations.append(recommendation)
        # 3. Store the recommendations for the current session, only for those module that are not using any kind of external logic. 
        if (module[0]['logic_filename'] == None):
            try:
                conn2    = mysql.connect()
                cursor2  = conn2.cursor()
                cursor2.execute("INSERT INTO session_recommendation (sessionID, recommendationID) VALUES (%s, %s)", (ID, recommendation['id']))
                conn2.commit()
            except Exception as e:
                raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
            finally:
                cursor2.close()
                conn2.close()
    cursor.close()
    conn.close()
    # print(result)

    # 4. Create ZIP with recommendations and guides
    # 4.1 Create the temporary directory to be zipped
    temp_dir = 'temp/session'+str(ID)+'/'
    if not os.path.exists(temp_dir):
        os.mkdir(temp_dir)
    # 4.2 Generate the PDF recommendations file    
    modules.utils.build_recommendations_PDF(module_name=module[0]['shortname'], session_id=ID, recommendations=result)
    # 4.3 Add guides to the temporary directory
    for recm in recommendations:
        if recm['recommendation_guide'] is not None:
            shutil.copyfile('external/'+str(recm['recommendation_guide']), temp_dir+str(recm['recommendation_guide']))
    # 4.4 Zip all the files
    zipped = modules.utils.create_recommendations_ZIP(module_name=module[0]['shortname'], session_id=ID)
    # 4.5 Remove all the files created to zip
    if zipped:
        shutil.rmtree(temp_dir)
    return(modules.utils.build_response_json(request.path, 200, result))  


"""
[Summary]: Adds a recommendation to a session, this method is exclusively used after the logic of a module is executed.
[Returns]: 
"""
def add_logic_session_recommendation(session_id, recommendation_id):
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("INSERT INTO session_recommendation (sessionID, recommendationID) VALUES (%s, %s)", (session_id, recommendation_id))
        conn.commit()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500) 
    finally:
        cursor.close()
        conn.close()

    # The recommendation is linked to the session.
    return (True)

"""
[Summary]: Counts number of closed sessions by module ID and user ID.
[Returns]: Returns response result.
"""
def count_sessions_of_user_module(module_id, user_id):
    # Let's get existing sessions from the database.
    try:
        conn    = mysql.connect()
        cursor  = conn.cursor()
        cursor.execute("SELECT COUNT(session_id) FROM view_user_sessions WHERE moduleID=%s AND user_id=%s AND ended=1 ORDER BY session_id DESC", (module_id, user_id))
        res = cursor.fetchall()
        cursor.close()
        conn.close()
    except Exception as e:
        raise modules.error_handlers.BadRequest(request.path, str(e), 500)

    if (res):
        return res[0][0]
    else:
        return 0

Get User Sessions

GET /api/sessions

Synopsis

Get user sessions.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Id of the session.

• module_id (int) – Id of the module executed on that session.

• user_id (int) – The session belongs to this user.

• ended (boolean) – Flag that indicates that a session was terminated by the user.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Sessions successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve sessions.

Example Response

{
   "/api/sessions":{
      "content":[
         {
            "id":1,
            "module_id":1,
            "user_id":2,
            "ended":0,
            "updatedOn":"Sat, 20 Nov 2021 10:31:41 GMT",
            "createdOn":"Sat, 20 Nov 2021 10:31:41 GMT"
         }
      ],
      "status":200
   }
}

Note

The end flag should be set to true when all the questions of a module were answered by a user.

---

GET /api/session/(int: id)

Synopsis

Get user session identified by id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – id of the session.

Response JSON Object

• id (int) – Id of the session.

• module_id (int) – Id of the module executed on that session.

• user_id (int) – The session belongs to this user.

• ended (boolean) – Flag that indicates that a session was terminated by the user.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Sessions successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve sessions.

Example Response

{
   "/api/sessions":{
      "content":[
         {
            "id":1,
            "module_id":1,
            "user_id":2,
            "ended":0,
            "updatedOn":"Sat, 20 Nov 2021 10:31:41 GMT",
            "createdOn":"Sat, 20 Nov 2021 10:31:41 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/session/user/(string: email)

Synopsis

Get sessions of a user identified by email.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• email (string) – Email of the user.

Response JSON Object

• id (int) – Id of the session or module.

• user_email (string) – The email of the user.

• ended (boolean) – Flag that indicates that a session was terminated by the user.

• type_id (int) – Module type id.

• shortname (string) – Unique short name or abbreviation.

• fullname (string) – Full name of the module.

• displayname (string) – Module display name that can be used by a frontend.

• dependencies (array) – An array that contains the set of modules that the current module depends on.

• description (string) – Module description.

• avatar (string) – Avatar of the user (i.e., location in disk).

• logic_filename (string) – Filename of the file containing the dynamic logic of the module.

• plugin (boolean) – A flag that sets if the current module is a plugin.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Sessions successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve sessions.

Example Response

{
   "/api/sessions/user/forrest@sam.pt":{
      "content":[
         {

            "id":1,
            "user_email":"forrest@sam.pt",
            "user_id":2,
            "ended":0,
            "module":{
               "id":1,
               "shortname":"SRE",
               "fullname":"Security Requirements Elicitation",
               "displayname":"Security Requirements",
               "description":null,
               "dependencies":[],
               "logic_filename":null,
               "type_id":null,
               "avatar":null,
               "createdon":"Fri, 19 Nov 2021 15:29:18 GMT",
               "updatedon":"Fri, 19 Nov 2021 15:29:18 GMT"
            },
            "createdOn":"Sat, 20 Nov 2021 10:31:41 GMT",
            "updatedOn":"Sat, 20 Nov 2021 10:31:41 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/session/closed

Synopsis

Get user sessions that were set as closed or terminated.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Response JSON Object

• id (int) – Id of the session, question, answer, or recommendation.

• module_id (int) – Id of the module executed on that session.

• user_id (int) – The session belongs to this user.

• ended (boolean) – Flag that indicates that a session was terminated by the user.

• content (string) – The content of question, answer, or recommendation.

• answer (array) – Selected answers for the current question and session.

• recommendation_guide (string) – The filename of the recommendation guide.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Sessions successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve sessions.

Example Response

{
   "/api/sessions/closed":{
      "content":[
         {
            "id":1,
            "user_id":2,
            "module_id":1,
            "ended":1,
            "questions":[
               {
                  "id":1,
                  "content":"What is the domain of your IoT system ?",
                  "answer":[{"id":1,"content":"Smart home"}],
               }
            ],
            "recommendations":[
               {
                  "id":1,
                  "content":"Confidentiality",
                  "description":null,
                  "recommendation_guide":null
               }
            ],
            "createdOn":"Sat, 20 Nov 2021 10:31:41 GMT",
            "updatedOn":"Sat, 20 Nov 2021 11:31:29 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/session/(int: id)/closed

Synopsis

Get user sessions identified by id that were flagged as closed.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the session.

Response JSON Object

• id (int) – Id of the session, question, answer, or recommendation.

• module_id (int) – Id of the module executed on that session.

• user_id (int) – The session belongs to this user.

• ended (boolean) – Flag that indicates that a session was terminated by the user.

• content (string) – The content of question, answer, or recommendation.

• answer (array) – Selected answers for the current question and session.

• recommendation_guide (string) – The filename of the recommendation guide.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Sessions successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve sessions.

Example Response

{
   "/api/sessions/closed":{
      "content":[
         {
            "id":1,
            "user_id":2,
            "module_id":1,
            "ended":1,
            "questions":[
               {
                  "id":1,
                  "content":"What is the domain of your IoT system ?",
                  "answer":[{"id":1,"content":"Smart home"}],
               }
            ],
            "recommendations":[
               {
                  "id":1,
                  "content":"Confidentiality",
                  "description":null,
                  "recommendation_guide":null
               }
            ],
            "createdOn":"Sat, 20 Nov 2021 10:31:41 GMT",
            "updatedOn":"Sat, 20 Nov 2021 11:31:29 GMT"
         }
      ],
      "status":200
   }
}

---

GET /api/session/module/(int: id)/user/(int: id)

Synopsis

Get user sessions that were flagged as closed for a particular user id and module id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the module or user.

Response JSON Object

• id (int) – Id of the session.

• user_id (int) – The session belongs to this user.

• user_email (string) – The email of the user.

• module_id (int) – Id of the module executed on that session.

• ended (boolean) – Flag that indicates that a session was terminated by the user.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Sessions successfully retrieved.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to retrieve sessions.

Example Response

{
   "/api/sessions/module/1/user/2":{
      "content":[
         {
            "id":1,
            "user_id":2
            "user_email":"forrest@sam.pt",
            "module_id":1,
            "ended":1,
            "createdOn":"Sat, 20 Nov 2021 10:31:41 GMT",
            "updatedOn":"Sat, 20 Nov 2021 11:31:29 GMT"
         }
      ],
      "status":200
   }
}

Create User Session

POST /api/session

Synopsis

Starts a new user session taking into account a user selected module identified by module_id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• module_id (int) – Id of the module that will be executed on that user session.

• email (string) – Email of the user who started the session.

Response JSON Object

• id (int) – Id of the new session.

• shortname (string) – Unique short name or abbreviation of the module.

• fullname (string) – Full name of the module.

• displayname (string) – Module display name that can be used by a frontend.

• description (string) – Module description.

• tree (array) – Array of questions and answers mapped to the module.

• dependencies (array) – An array that contains the set of modules that the current module depends on.

• recommendations (array) – Array of recommendations that contains the mapping between question id and answer id.

• tree – Array of questions and answers mapped to the module.

• createdon (datetime) – Creation date and time.

• updatedon (datetime) – Update date and time.

• status (int) – Status code.

Status Codes

• 200 OK – Session successfully created.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to create session.

Example Request

{"module_id":1,"email":"forrest@sam.pt"}

Example Response

{
   "/api/session":{
      "id":1,
      "module":[
         {
            "id":1,
            "shortname":"SRE",
            "displayname":"Security Requirements",
            "fullname":"Security Requirements Elicitation",
            "description":"Module description",
            "avatar":null,
            "logic_filename":null,
            "type_id":null,
            "dependencies":[],
            "recommendations":[
               {
                  "id":1,
                  "content":"Confidentiality",
                  "questions_answers":[
                     {
                        "id":1,
                        "question_id":1,
                        "answer_id":1,
                        "createdon":"Sat, 20 Nov 2021 11:55:12 GMT",
                        "updatedon":"Sat, 20 Nov 2021 11:55:12 GMT"
                     }
                  ],
                  "createdon":"Sat, 20 Nov 2021 11:55:12 GMT",
                  "updatedon":"Sat, 20 Nov 2021 11:55:12 GMT"
               }
            ],
            "tree":[
               {
                  "id":1,
                  "order":0,
                  "name":"What is the domain of your IoT system ?",
                  "multipleAnswers":0,
                  "type":"question",
                  "expanded":false,
                  "children":[
                     {"id":1, "name":"Smart home", "type":"answer", "children":[]},
                     {"id":2, "name":"Smart Healthcare", "type":"answer", "children":[]}
                  ]
               }
            ],
            "createdon":"Sat, 20 Nov 2021 11:55:12 GMT",
            "updatedon":"Sat, 20 Nov 2021 11:55:12 GMT"
         }
      ],
      "status":200
   }
}

Edit User Session

PUT /api/session

Synopsis

Update a session. Specifically, by adding an answer to a question for the session module.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Request JSON Object

• question_id (int) – Id of the module that will be executed on that user session.

• answer_id (int) – Email of the user who started the session.

• input (string) – (optional) User direct answer that was not choosen from a predefined set of answers.

Response JSON Object

• status (int) – Status code.

Status Codes

• 200 OK – Session successfully created.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to create session.

Example Request

{"question_id":1, "answer_id":1}

Important

The input parameter should only be included in the request body if the question is not a multi-choice one where the user has to include a direct answer:

{"question_id":1, "input":"This is the user answer"}

Example Response

{"/api/session/1":{"status":200}}

Close User Session

PUT /api/session/{id}/end

Synopsis

Close or terminate a user session through the session id.

Request Headers

• Authorization – Bearer token provided by /api/user/login.

Response Headers

• Content-Type – application/json

Parameters

• id (int) – Id of the session.

Response JSON Object

• id (int) – Id of the session that was closed.

• recommendations (array) – An array that contains the recommendations based on the answers given by the user in the session.

• status (int) – Status code.

Status Codes

• 200 OK – Session successfully closed.

• 400 Bad Request – The server was unable to process the request (e.g., malformed request syntax).

• 500 Internal Server Error – Fail to close session.

Note

This service will return the set of recommendations based on the answers given by the user in that session.

Example Response

{
   "/api/session/1/end":{
      "id":1,
      "recommendations":[
         {
            "id":1,
            "content":"Confidentiality",
            "description":null,
            "recommendation_guide":null
         }
      ],
      "status":200
   }
}

Acknowledgment

This work was performed under the scope of Project SECURIoTESIGN with funding from FCT/COMPETE/FEDER with reference number POCI-01-0145-FEDER-030657. This work is funded by Portuguese FCT/MCTES through national funds and, when applicable, co-funded by EU funds under the project UIDB/50008/2020, research grants BIL/Nº11/2019-B00701, BIL/Nº12/2019-B00702, and FCT research and doctoral grant SFRH/BD/133838/2017 and BIM/n°32/2018-B00582, respectively, and also supported by project CENTRO-01-0145-FEDER-000019 - C4 - Competence Center in Cloud Computing, Research Line 1: Cloud Systems, Work package WP 1.2 - Systems design and development processes and software for Cloud and Internet of Things ecosystems, cofinanced by the European Regional Development Fund (ERDF) through the Programa Operacional Regional do Centro (Centro 2020), in the scope of the Sistema de Apoio à Investigação Científica e Tecnológica - Programas Integrados de IC&DT.

License

Apache License

Version 2.0, January 2004

http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

   “License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

   “Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

   “Legal Entity” shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, “control” means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

   “You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by this License.

   “Source” form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

   “Object” form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

   “Work” shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

   “Derivative Works” shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

   “Contribution” shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, “submitted” means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as “Not a Contribution.”

   “Contributor” shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:

   1. You must give any other recipients of the Work or Derivative Works a copy of this License; and

   2. You must cause any modified files to carry prominent notices stating that You changed the files; and

   3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and

   4. If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

   You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS