M2OLA/API_Interfaces.txt

#######################
LoginAPI (api/login)
#######################
POST -> Authentication method
    In:
        email = Email and login of the user (must be unique)
        password = Password of the user (secured by HTTPS)
    Out:
        200 -> AUTH_RESULT = "OK" : Authentication sucessful
        401 -> AUTH_RESULT = "AUTHENTICATION_FAILURE" : Wrong login/password
        403 -> AUTH_RESULT = "NOT_ALLOWED" : User is not allowed for this application
        201 -> AUTH_RESULT = "ALREADY_LOGGED" : A user is already logged on this session

DELETE -> Logout current user
    Out:
        200 -> AUTH_RESULT = "OK" : Logout sucessful


#######################
UserInfoAPI (api/userInfo)
#######################
GET -> Get the current logged user, return None if no one is connected
    Out:
        200 -> USER = <USER_OBJECT>|null : Dictionary containing user infos or null

########################
UserAPI (api/user)
########################
POST -> Create a user if it not already exists
    In:
        email = Email and login of the user (must be unique)
        role = Role of the user (can be concatenated with -) 1=secrétaire, 2=resp_formation, 3=tuteur_univ, 4=étudiant, 5=tuteur_ent
        name = Display name of the user
    Out:
        200 -> UID = <USER_ID> : The user already exists with the id USER_ID
        201 -> UID = <USER_ID> : The user has been successfully created with the id USER_ID
        400 -> ERROR = "One or more parameters are missing" : Bad request

PUT -> Modify an existing user
    In: (Suffix = /byuid/<USER_ID>)
        role = Role of the user (can be concatenated with -) 1=secrétaire, 2=resp_formation, 3=tuteur_univ, 4=étudiant, 5=tuteur_ent
        phone = Phone number of the user (00.00.00.00.00)
        email = Email of the user (must be unique)
    Out:
        200 -> UID = <USER_ID> : The user has been modified sucessfully with the id USER_ID
        400 -> ERROR = "One or more parameters are missing !" : Bad request
        405 -> ERROR = "This user doesn't exists !" : Bad USER_ID provided
        405 -> ERROR = "A user with this email already exists !" : A user with this email already exists

GET -> Getting specified user infos
    In: (Suffixes = /byuid/<USER_ID> | /byemail/<USER_EMAIL>)
    Out:
        200 -> USER = <USER_OBJECT>|null : Dictionary containing user infos or null

########################
GroupAPI (api/group)
########################
POST -> Create a group if it not already exists
    In:
        name = Name of the group (must be unique)
        year = Parameter setting the year
        class_short = Parameter setting the short name of the class
        class_long = Parameter setting the full name of the class
        department = Parameter setting the name of the class's department
        resp_id = UID of the group's responsible
        sec_id = UID of the group's secretary
    Out:
        200 -> GID = <GROUP_ID> : The group already exists with the id GROUP_ID
        201 -> GID = <GROUP_ID> : The group has been successfully created with the id GROUP_ID
        400 -> ERROR = "One or more parameters are missing" : Bad request
        400 -> ERROR = "The user with id <USER_ID> doesn't exists !" : The given USER_ID for resp_id or sec_id is not found

PUT -> Modify an existing group
    In: (Suffix = /bygid/<GROUP_ID>)
        name = Name of the group (must be unique)
        year = Parameter setting the year
        class_short = Parameter setting the short name of the class
        class_long = Parameter setting the full name of the class
        department = Parameter setting the name of the class's department
        resp_id = UID of the group's responsible
        sec_id = UID of the group's secretary
    Out:
        200 -> GID = <GROUP_ID> : The group has been modified sucessfully with the id GROUP_ID
        400 -> ERROR = "One or more parameters are missing !" : Bad request
        400 -> ERROR = "The user with id <USER_ID> doesn't exists !" : The given USER_ID for resp_id or sec_id is not found
        405 -> ERROR = "This group doesn't exists !" : Bad GROUP_ID provided
        405 -> ERROR = "A group with this name already exists !" : A group with this name already exists

GET -> Getting specified group infos
    In: (Suffixes = /bygid/<GROUP_ID> | /byname/<GROUP_NAME> )
    Out:
        200 -> GROUP = <GROUP_OBJECT>|null : Dictionary containing group infos or null

OPTIONS -> Add pairs of users (student/tutor) to the group
    In:
        pairs -> Table of pairs student's uid/tutor's uid (ex: [[1,2],[3,2]])
    Out:
        200 -> RESULT = "Pairs added successfully"
        400 -> ERROR = "One or more parameters are missing !" : Bad request
        400 -> ERROR = "The user with id <USER_ID> doesn't exists !" : The given USER_ID for student or tutor is not found
        400 -> ERROR = "A student must have the 'student' role !" : The given USER_ID for student doesn't have the "student" role (4)
        400 -> ERROR = "A student can't be a tutor !" : The given USER_ID for tutor have the "student" role (4) and so can't be a tutor
        405 -> ERROR = "This group doesn't exists !" : Bad GROUP_ID provided
        409 -> ERROR = "Pairs are incorrectly formed !" : Bad syntax in pairs table

########################
LivretAPI (api/livret)
########################
POST -> Create a livret if it not already exists
    In:
        group_id = Id of the group where this livret should be inserted in (we must have only one livret per student in a single group)
        etutor_id = UID of the company tutor
        company_name = Name of the company
        company_address = Mail address of the company
        contract_type = Type of the internship contract (1 = contrat d'alternance, 2 = contrat de professionnalisation, 3 = stage)
        contract_start = Date of the contract's beginning (format : dd-mm-yyyy)
        contract_end = Date of the contract's end (format : dd-mm-yyyy)
        description = Description of the internship missions and activities overview
    Out:
        200 -> LID = <LIVRET_ID> : The livret already exists with the id LIVRET_ID
        201 -> LID = <LIVRET_ID> : The livret has been successfully created with the id LIVRET_ID
        400 -> ERROR = "One or more parameters are missing" : Bad request
        400 -> ERROR = "The user with id <USER_ID> doesn't exists !" : The given USER_ID for etutor is not found
        400 -> ERROR = "An etutor must have the 'etutor' role !" : The given USER_ID for etutor doesn't have the "etutor" role (5)
        400 -> ERROR = "The contract start can't be after its end !" : The given contract's end date is anterior to it's beginning
        405 -> ERROR = "The group with id GROUP_ID doesn't exists !" : The given GROUP_ID is not found
        405 -> ERROR = "The The current student is not registered in the group <GROUP_ID> !" : The currently logged student is not affected to the specified GROUP_ID

PUT -> Modify an existing livret
    In: (Suffix = /bylid/<LIVRET_ID>)
        etutor_id = UID of the company tutor
        company_name = Name of the company
        company_address = Mail address of the company
        contract_type = Type of the internship contract (1 = contrat d'alternance, 2 = contrat de professionnalisation, 3 = stage)
        contract_start = Date of the contract's beginning (format : dd-mm-yyyy)
        contract_end = Date of the contract's end (format : dd-mm-yyyy)
        description = Description of the internship missions and activities overview
    Out:
        200 -> LID = <LIVRET_ID> : The livret has been modified successfully with the id LIVRET_ID
        400 -> ERROR = "One or more parameters are missing !" : Bad request
        400 -> ERROR = "The user with id <USER_ID> doesn't exists !" : The given USER_ID for etutor is not found
        400 -> ERROR = "An etutor must have the 'etutor' role !" : The given USER_ID for etutor doesn't have the "etutor" role (5)
        400 -> ERROR = "The contract start can't be after its end !" : The given contract's end date is anterior to it's beginning
        405 -> ERROR = "This group doesn't exists !" : Bad LIVRET_ID provided

GET -> Getting specified livret infos
    In: (Suffixes = /bylid/<GROUP_ID> | /bytutorship/<GROUP_ID>/<STUDENT_ID> )
    Out:
        200 -> LIVRET = <LIVRET_OBJECT>|null : Dictionary containing livret infos or null