a7_openapi.yaml

openapi: 3.0.0

info:
    version: '1.0'
    title: 'LBAW UNI-versal Web API'
    description: 'Web resources specification (A7) for UNI-versal'

servers:
    - url: http://lbaw-prod.fe.up.pt
      description: Production server

externalDocs: 
    description: Find more info here.
    url: https://git.fe.up.pt/lbaw/lbaw2122/lbaw2106/-/wikis/home

tags: 
    - name: 'M01: Authentication and Profile'
    - name: 'M02: Questions and Users'
    - name: 'M03: Post review'
    - name: 'M04: Post management'
    - name: 'M05: User management'
    - name: 'M06: Static Pages'

paths:

    #-------------------- M01 --------------------

    # login
    /login:
        get:
            operationId: R101
            summary: 'R101: Login Form'
            description: 'Provide login form. Access: VIS'
            tags:
              - 'M01: Authentication and Profile'

            responses:
              '200':
                description: 'Ok. Show login form UI.'


        post:
            operationId: R102
            summary: 'R102: Login Action'
            description: 'Login to the website. Access: VIS' 
            tags: 
            - 'M01: Authentication and Profile'

            requestBody:
                required: True
                content:
                    application/x-www-form-urlencoded:
                        schema:
                            type: object
                            properties:
                                password:
                                    type: string
                                email:
                                    type: string
                            required:
                                - inputPassword
                                - inputEmail
            responses:
                '302':
                    description: 'Redirect after login'
                    headers:
                      Location:
                        schema:
                          type: string
                        examples:
                          302Success:
                              description: 'Ok. Redirect to Home Page'
                              value: '/'
                          302Error:
                              description: 'Failed Authentication. Redirect to login form.'
                              value: '/login'


    /logout:
        post:
            operationId: R102
            summary: 'R102: Logout Action'
            description: 'Logout the current authenticated user. Access: USR'
            tags:
                - 'M01: Authentication and Profile'
            responses:
                '302':
                    description: 'Redirect after processing logout.'
                    headers:
                        Location:
                          schema:
                            type: string
                          examples:
                              302Success:
                                  description: 'Successful logout. Redirect to homepage.'
                                  value: '/'


    /register:
        get:
            operationId: R104
            summary: 'R104: Signup Form'
            description: 'Provide signup form. Access: VIS'
            tags:
              - 'M01: Authentication and Profile'
            responses:
              '200':
                description: 'Ok. Show sign-up form UI.'

        post:
            operationId: R105
            summary: 'R105: Signup Action'
            description: 'Signup to the website'
            tags:
                - 'M01: Authentication and Profile'
            
            requestBody:
                    required: True
                    content:
                        application/x-www-form-urlencoded:
                            schema:
                                type: object
                                properties:
                                    name:
                                        type: string
                                    password:
                                        type: string
                                    email:
                                        type: string
                                required:
                                    - name
                                    - password
                                    - email
            responses:
                '302':
                    description: 'Redirect after processing signup credentials.'
                    headers:
                      Location:
                        schema:
                          type: string
                        examples:
                            302Success:
                                description: 'Successful credential insertion. Redirect to e-mail confirmation notice.'
                                value: '/email/verify'
                            302Error: 
                                description: 'Failed credential insertion. Redirect to signup form'
                                value: '/register'



    /email/verify:
        get:
            operationId: R105
            summary: 'R105: Email verification notice'
            description: 'Provide email verification notice. Access: USR'
            tags:
                - 'M01: Authentication and Profile'
            responses:
              '200':
                description: 'Ok. Show email verification notice UI.'

       

    
    /users/{id}/profile:

        get:
            operationId: R106
            summary: 'R107: View user profile'
            description: 'Show the individual user profile. Access: USR'
            tags:
                - 'M01: Authentication and Profile'

            parameters:
              - in: path
                name: id
                schema:
                    type: integer
                required: true

            responses:
                '200':
                  description: 'Ok. Show profile UI.'
        post:
            operationId: R108
            summary: 'R108: Edit Profile Action'
            description: 'Processes the new user edition form submission. Access: USR'
            tags:
                - 'M01: Authentication and Profile'
            
            parameters:
              - in: path
                name: id
                schema:
                    type: integer
                required: true

            requestBody:
                required: true
                content:
                  application/x-www-form-urlencoded:
                    schema:
                        type: object
                        properties:
                            name:
                                type: string
                            picture:
                                type: string
                                format: binary
                            email:
                                type: string
                            role:
                                type: string
                            faculty:
                                type: string
                            area:
                                type: string


            responses:
              '302':
                description: 'Redirect after processing the user new information.'
                headers:
                    Location:
                      schema:
                          type: string
                      examples:
                          302Success:
                            description: 'Successful profile edition. Redirect to user profile.'
                            value: '/users/{id}/profile'
                          302Failure:
                            description: 'Failed to edit. Redirect to user profile.'
                            value: '/users/{id}/profile'
    
    /users/{id}/profile/edit:
        get: 
            operationId: R107
            summary: 'R107: View user profile edit form'
            description: 'Show the individual user profile edition form. Access: USR'
            tags:
                - 'M01: Authentication and Profile'

            parameters:
              - in: path
                name: id
                schema:
                    type: integer
                required: true

            responses:
                '200':
                  description: 'Ok. Show profile edition form UI.'


    /user/{id}/notifications:

      get: 
            operationId: R108
            summary: 'R108: View notifications'
            description: "Show the user's notifications. Access: USR"
            tags:
                - 'M01: Authentication and Profile'

            parameters:
              - in: path
                name: id
                schema:
                    type: integer
                required: true

            responses:
                '200':
                  description: 'Ok. Show notifications.'
        
# -------------------- M02 --------------------

    /topics/{topic_name}:
      get:
        operationId: R201
        summary: 'R201: Get Topic Page'
        description: 'Show the page where questions of a certain topic are listed. Access: USR'
        tags: 
          - 'M02: Questions and Users'

        parameters: 
          - in: path
            name: id
            schema:
                type: integer
            required: true  

        responses:
          '200':
            description: 'Ok. Show Topic UI'

    /search:
      get:
        operationId: R202
        summary: 'R202: Get Search Question Results'
        description: 'Load the questions most relevant for a given search. Access: USR'
        tags:
          - 'M02: Questions and Users'

        parameters:
          - in: query
            name: query
            description: 'String to use for full-text search'
            schema:
              type: string
            required: true

        responses:
          '302':
            description: 'Redirect after processing the information.'
            headers:
                Location:
                  schema:
                      type: string
                  examples:
                      302Success:
                        description: 'Redirect to search questions.'
                        value: '/search/questions'
    
    /search/{search-input}/questions/:
      get:
        operationId: R203
        summary: 'R202: Get Search Question Results'
        description: 'Load the questions most relevant for a given search. Access: USR'
        tags:
          - 'M02: Questions and Users'

        parameters:
          - in: query
            name: query
            description: 'String to use for full-text search'
            schema:
              type: string
            required: true

        responses:
          '200':
            description: 'Ok. Show questions search results UI'

    /search/{search-input}/users/:
      get:
        operationId: R204
        summary: 'R202: Get Search Question Results'
        description: 'Load the users most relevant for a given search. Access: USR'
        tags:
          - 'M02: Questions and Users'

        parameters:
          - in: query
            name: query
            description: 'String to use for full-text search'
            schema:
              type: string
            required: true

        responses:
          '200':
            description: 'Ok. Show user search results UI'
          

    /search/{search-input}/users/filtered:
      get:
        operationId: R205
        summary: 'R205: Filter User Results'
        description: 'Filter the users by a given parameter. Acess: USR'
        tags:
          - 'M02: Questions and Users'

        parameters:
          - in: query
            name: filteringParameter
            schema:
              type: string
            required: true
        
        responses:
          '200':
            description: 'Ok. Show user search results UI with filtered users'
    

    /search/{search-input}/questions/filtered:
      get:
        operationId: R205
        summary: 'R205: Filter User Results'
        description: 'Filter and sort the questions by different parameters. Acess: USR'
        tags:
          - 'M02: Questions and Users'

        parameters:
          - in: query
            name: filteringParameter
            schema:
              type: string
            required: true
          - in: query
            name: sortingParameter
            schema:
              type: string
            required: true
          - in: query
            name: topic
            schema:
              type: string
            required: true
        
        responses:
          '200':
            description: 'Ok. Show user search results UI with filtered questions'
    
    #-------------------- M03 --------------------
  
    /question/{id}/upvote:

      post:
        operationId: R301
        summary: 'R301: Upvote post'
        description: 'Authenticated user upvotes the current post rating'
        tags: 
            - 'M03: Post review'

        parameters:
          - in: path
            name: id
            schema:
              type: integer
            required: true
          - in: path
            name: post_id
            schema:
              type: integer
            required: true
        
        responses:
          '200':
            description: 'Upvote action was successful.'

    /question/{id}/bookmark:
        
        post:
            operationId: R302
            summary: 'R303: Bookmark post'
            description: 'Authenticated user bookmarks the current post'
            tags: 
                - 'M03: Post review'

            parameters:
              - in: path
                name: id
                schema:
                  type: integer
                required: true
              - in: query
                name: id_USRer
                schema:
                  type: integer
                required: true
            
            responses:
              '200':
                description: 'Bookmarking was successful.'
  

#-------------------- M04 --------------------#
    
    /questions/create:

        get:
            operationId: R401
            summary: 'R401: Create question'
            description: 'Show the question creation form page. Access: USR'
            tags:
            - 'M04: Post management'

            responses:
              '200':
                description: 'Ok. Show question form'

        post:
            operationId: R402
            summary: 'R402: Question creating action'
            description: 'Processes the creation of a new question. Access: USR' 
            tags: 
            - 'M04: Post management'

            requestBody:
                required: True
                content:
                    application/x-www-form-urlencoded:
                        schema:
                            type: object
                            properties:
                                author:
                                    type: string
                                tag:
                                    type: string
                                title:
                                    type: string
                                body:
                                    type: string
                                topic:
                                    type: string
                                files:
                                    type: array
                                    items:
                                        type: integer
                                        format: binary 
                                images: 
                                    type: array
                                    items: 
                                        type: integer
                                        format: binary 
                                
                            required:
                                - title
                                - body
                                - topic
            responses:
                '302':
                    description: 'Redirect after processing the new question information'
                    headers:
                        Location:
                            schema:
                                type: string
                            examples:
                                302Success:
                                    description: 'Sucessfull question creation. Redirected to the question page.'
                                    value: '/question/{id}'
                                302Error:
                                    description: 'Failed question creation. Redirected to the question creation form page.'
                                    value: '/questions/create'
        
    /question/{id}:

        get:
            operationId: R403
            summary: 'R403: View question'
            description: 'Show the question. Access: USR'
            tags:
            - 'M04: Post management'

            responses:
              '200':
                description: 'Ok. Show question'



    /question/{id}/answer:

        post:
            operationId: R404
            summary: 'R404: Answer to a question'
            description: 'Processes the creation of a new answer. Access: USR' 
            tags: 
            - 'M04: Post management'
            requestBody:
                required: True
                content:
                    application/x-www-form-urlencoded:
                        schema:
                            type: object
                            properties:
                                author:
                                    type: string
                                body:
                                    type: string
                                files:
                                    type: string
                                    format: binary
                            
                            required:
                                - body
                                - author                                
            responses:
                '302':
                    description: 'Redirect after publishing the new answer'
                    headers:
                        Location:
                            schema:
                                type: string
                            examples:
                                301Success:
                                    description: 'Sucessfull answer creation. Redirected to the specific question page.'
                                    value: '/question/{id}'
                                301Error:
                                    description: 'Failed answer creation. Redirected to the specific question page.'
                                    value: '/question/{id}'


    /post/{id}/delete:

        delete:
            operationId: R405
            summary: 'R405: Answer deletion action'
            description: 'Processes the deletion of a answer. Access: OWN' 
            tags: 
            - 'M04: Post management'

            parameters:
              - in: path
                name: id
                schema:
                  type: integer
                required: true


            responses:
                '302':
                    description: 'Redirect after deleting the answer'
                    headers:
                        Location:
                            schema:
                                type: string
                            examples:
                                302Success:
                                    description: 'Sucessfull deletion. Redirected to the specific question page.'
                                    value: 'question/{id}'
                                302Error:
                                    description: 'Failed deletion. Redirected to the specific answer page.'
                                    value: 'question/{id}'


    /user/{id}/drafts:

        get:
            operationId: R407
            summary: 'R407: View drafts'
            description: 'Show drafts page. Access: OWN'
            tags:
            - 'M04: Post management'
            responses:
              '200':
                description: 'Ok. Show drafts'


    /user/{id}/drafts/{id_draft}:

        delete:
            operationId: R408
            summary: 'R408: Draft deleting action'
            description: 'Processes the deletion of a draft. Access: OWN' 
            tags: 
            - 'M04: Post management'

            parameters:
              - in: path
                name: id
                schema:
                  type: integer
                required: true
              - in: path
                name: id_draft
                schema:
                  type: integer
                required: true

            responses:
                '302':
                    description: 'Redirect after deleting the draft'
                    headers:
                        Location:
                            schema:
                                type: string
                            examples:
                                302Success:
                                    description: 'Sucessfull deletion. Redirected to the specific topic page.'
                                    value: '/user/{id}/drafts'
                                302Error:
                                    description: 'Failed deletion. Redirected to the specific topic page.'
                                    value: '/user/{id}/drafts'

        get:
            operationId: R409
            summary: 'R409: Import chosen draft'
            description: 'Import the data from the selected draft. Access: OWN'
            tags:
            - 'M04: Post management'

            parameters:
              - in: path
                name: id
                schema:
                  type: integer
                required: true
              - in: path
                name: id_draft
                schema:
                  type: integer
                required: true
                
            responses:
                '200':
                  description: 'Redirect after choosing the draft'
                  headers:
                        Location:
                            schema:
                                type: string
                            examples:
                                302Success:
                                    description: 'Sucessfull loading draft. Redirected to the question creation page.'
                                    value: '/questions/create'
                                302Error:
                                    description: 'Failed to load draft. Redirected to the drafts page.'
                                    value: '/user/{id}/drafts'
          



      #-------------------- M05 --------------------

    /moderator/{id}:

      get:
          operationId: R501
          summary: 'R501: Moderator View'
          description: 'Show the moderator page. Access: MOD'
          tags:
              - 'M05: User management'

          parameters:
              - in: path
                name: id
                schema:
                    type: integer
                required: true

          responses:
              '200':
                  description: 'Ok. Show moderator page.'



    /user/{id}/ban:
        delete:
            operationId: R502
            summary: 'R502: Ban USRer'
            description: 'Processes the USRer banning request. Access: MOD'
            tags:
                - 'M05: User management'

            parameters:
            - in: path
              name: id
              schema:
                type: integer
              required: true

            responses:
              '302':
                description: 'Redirect after USRer banning.'
                headers:
                  Location:
                    schema:
                      type: string
                    examples:
                      302Success:
                        description: 'Successful banning. Redirect to home page.'
                        value: '/'
                      302Failure:
                        description: "Failed to ban. Redirect to USRer's profile page."
                        value: 'user/{id}/profile'



    /systemNotifications:

        get:
            operationId: R503
            summary: 'R504: Access system notification page'
            description: 'Accesses the system notification page. Access: ADM'
            tags:
              - 'M05: User management'

            responses:
              '200':
                  description: 'Ok. Show moderator page.'
          
        post:
            operationId: R504
            summary: 'R504: Generate system notification'
            description: 'Processes the system notification request. Access: ADM'
            tags:
                - 'M05: User management'
            
            requestBody:
                required: true
                content:
                    application/x-www-form-urlencoded:
                        schema:
                            type: object
                            properties:
                                title:
                                    type: string
                                body:
                                    type: string
                            required:
                                - title
                                - body

            responses:
                '302':
                    description: 'Redirect after processing system notification creation request.'
                    headers:
                        Location:
                          schema:
                            type: string
                          examples:
                                302Success:
                                    description: 'Successful system notification creation. Redirect to home page.'
                                    value: '/'
                                302Error: 
                                    description: 'Failed credential insertion. Redirect to home page'
                                    value: '/systemNotifications'

    /user/{id}/promote:
        
        post:
            operationId: R505
            summary: 'R505: Promote USRer to moderator'
            description: 'Processes the promotion of a USRer to moderator. Access: MOD'
            tags:
                - 'M05: User management'
            
            requestBody:
                required: true
                content:
                    application/x-www-form-urlencoded:
                        schema:
                            type: object
                            properties:
                                USRerName:
                                    type: string
                                yourPassword:
                                    type: string
                            required:
                                - USRerName
                                - yourPassword
                                - repeatYourPassword

            responses:
                '302':
                    description: 'Redirect after processing system notification creation request.'
                    headers:
                        Location:
                          schema:
                            type: string
                          examples:
                                302Success:
                                    description: 'Successful promotion. Redirect to profile page.'
                                    value: '/user/{id}'
                                302Error: 
                                    description: 'Failed promotion. Redirect to profile page'
                                    value: '/user/{id}'

              


  # -------------------- M06 --------------------


    /about:
      get:
        operationId: R601
        summary: 'R601: About/Faq'
        description: 'Show the about/faq page. Access: VIS'
        tags:
          - 'M06: Static Pages'

        responses:
          '200':
            description: 'Ok. Show About/Faq UI'

    /:
      get:
        operationId: R602
        summary: 'R602: Home'
        description: 'Show the home page. Access: VIS'
        tags:
          - 'M06: Static Pages'
        
        responses:
          '200':
            description: 'Ok. Show Home Page UI'
    
    /contact:
      get:
        operationId: R603
        summary: 'R603: Contact'
        description: 'Show contact page. Access: VIS'
        tags:
          - 'M06: Static Pages'

        responses:
          '200':
            description: 'Ok. Show Home Page UI'