a7_openapi.yaml

openapi: '3.0.2'

info:
  title: 'Community Connect Web API'
  version: '1.0'
  description: 'Web Resources Specification (A7) for Community Connect'

servers:
  - url: https://lbaw23114.lbaw.fe.up.pt
    description: Production server

externalDocs:
 description: Find more info here.
 url: https://git.fe.up.pt/lbaw/lbaw2324/lbaw23114/-/wikis/eap

tags:
 - name: 'M01: Authentication'
 - name: 'M02: Profile'
 - name: 'M03: Questions'
 - name: 'M04: Answers'
 - name: 'M05: Administration'

paths:

# M01: Authentication

# Login

  /login:

    get:
      operationId: R101
      summary: 'R101: Login form'
      description: 'Provide login form. Access: PUB'
      tags:
        - 'M01: Authentication'
      responses:
        '200':
          description: 'Ok. Show login UI.'
        
    post:
      operationId: R102
      summary: 'R102: Login action'
      description: 'Processes the login form submission. Access: PUB'
      tags:
        - 'M01: Authentication'

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username_or_email:
                  type: string
                password:
                  type: string
                  format: password
              required:
                - username_or_email
                - password
      
      responses:
       '302':
         description: 'Redirect after processing the login credentials.'
         headers:
           Location:
             schema:
               type: string
             examples:
               302Success:
                 description: 'Successful authentication. Redirect to questions page.'
                 value: '/questions'
               302Failure:
                 description: 'Failed authentication. Redirect to login page.'
                 value: '/login'

# Logout

  /logout:

   get:
     operationId: R103
     summary: 'R103: Logout action'
     description: 'Logout the current user. Access: USR, OWN, ADM'
     tags:
       - 'M01: Authentication'
     responses:
       '302':
         description: 'Redirect after processing logout.'
         headers:
           Location:
             schema:
               type: string
             examples:
               302Success:
                 description: 'Successful logout. Redirect to questions page.'
                 value: '/questions'

# Register

  /register:

    get:
      operationId: R104
      summary: 'R104: Register form'
      description: 'Provide registration form. Access: PUB'
      tags:
        - 'M01: Authentication'
      responses:
        '200':
          description: 'Ok. Show registration UI.'

    post:
      operationId: R105
      summary: 'R105: Register action'
      description: 'Processes the registration form submission. Access: PUB'
      tags:
        - 'M01: Authentication'

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
                password_confirmation:
                  type: string
                  format: password
              required:
                - username
                - email
                - password
                - password_confirmation

      responses:
        '302':
          description: 'Redirect after processing the register credentials.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: 'Successful registration. Redirect to questions page.'
                  value: '/questions'
                302Failure:
                  description: 'Failed registration. Redirect to register page.'
                  value: '/register'

# M02: Profile

# View and Edit Profile

  /users/{id}:

    get:
      operationId: R201
      summary: 'R201: View profile'
      description: "Shows an user's profile page. Access: PUB, USR, OWN, ADM"
      tags:
        - 'M02: Profile'

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

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

    post:
      operationId: R202
      summary: 'R202: Edit profile action'
      description: "Processes editions on an user's profile. Access: OWN, ADM"
      tags:
        - 'M02: Profile'

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

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
                confirm_password:
                  type: string
                  format: password
              required:
                - username
                - email
                - password
                - confirm_password

      responses:
        '302':
          description: "Redirect after processing the edition on the user's profile."
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: 'Successful edition. Redirect to profile page.'
                  value: '/user/{id}'
                302Failure:
                  description: 'Failed edition. Redirect to profile edition page.'
                  value: '/user/{id}/edit'
        '403':
          description: 'This action is unauthorized.'

# Edit Profile Form

  /users/{id}/edit:

    get:
      operationId: R203
      summary: 'R203: Edit profile form'
      description: "Provide user's profile edition form. Access: OWN, ADM"
      tags:
        - 'M02: Profile'

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

      responses:
        '200':
          description: "Ok. Show user's profile edition UI."
        '403':
          description: 'This action is unauthorized.'

# M03: Questions

# View Questions and Create Question Action

  /questions:

    get:
      operationId: R301
      summary: 'R301: View questions'
      description: 'Shows all questions.  Access: PUB, USR, OWN, ADM'
      tags:
        - 'M03: Questions'
      responses:
        '200':
          description: 'Ok. Show all questions.'

    post:
      operationId: R302
      summary: 'R302: Create question action'
      description: 'Processes question form submission. Access: USR, OWN, ADM'
      tags:
        - 'M03: Questions'

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                title:
                  type: string
                  format: string
                content:
                  type: string
                  format: string
                id_user:
                  type: integer
                  format: integer
                id_community:
                  type: integer
                  format: integer
              required:
                - title
                - content
                - id_user
                - id_community
      
      responses:
        '302':
         description: 'Redirect after processing the question submission.'
         headers:
           Location:
             schema:
               type: string
             examples:
               302Success:
                 description: 'Successful question submission. Redirect to questions page.'
                 value: '/questions'
        '403':
          description: 'This action is unauthorized.'

# Create Question Form

  /questions/create:

    get:
      operationId: R303
      summary: 'R303: Create question form'
      description: "Provide question's creation form. Access: USR, OWN, ADM"
      tags:
        - 'M03: Questions'
      responses:
        '200':
          description: "Ok. Show question's creation UI."
        '403':
          description: 'This action is unauthorized.'

# View and Edit Question

  /questions/{id}:

    get:
      operationId: R304
      summary: 'R304: View question'
      description: 'Shows a question. Access: PUB, USR, OWN, ADM'
      tags:
        - 'M03: Questions'
      
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: True

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

    post:
      operationId: R305
      summary: 'R305: Edit question action'
      description: "Processes editions on a question. Access: OWN, ADM"
      tags:
        - 'M03: Questions'

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

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                title:
                  type: string
                  format: string
                content:
                  type: string
                  format: string
              required:
                - title
                - content
      
      responses:
        '302':
         description: 'Redirect after processing the question edition.'
         headers:
           Location:
             schema:
               type: string
             examples:
               302Success:
                 description: 'Successful question edition. Redirect to question page.'
                 value: '/questions/{id}'
        '403':
          description: 'This action is unauthorized.'

# Edit Question Form

  /questions/{id}/edit/:

    get:
      operationId: R306
      summary: 'R306: Edit question form'
      description: "Provide question's edition form. Access: OWN, ADM"
      tags:
        - 'M03: Questions'

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

      responses:
        '200':
          description: "Ok. Show question's edition UI."
        '403':
          description: 'This action is unauthorized.'

# Delete Question

  /questions/{id}/delete:

    post:
      operationId: R307
      summary: 'R307: Delete question action'
      description: 'Processes question deletion. Access: OWN, ADM'
      tags:
        - 'M03: Questions'

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

      responses:
        '302':
         description: 'Redirect after processing the question deletion.'
         headers:
           Location:
             schema:
               type: string
             examples:
               302Success:
                 description: 'Successful question deletion. Redirect to questions page.'
                 value: '/questions'
        '403':
          description: 'This action is unauthorized.'

# Search Questions

  /api/questions:

    get:
      operationId: R308
      summary: 'R308: Search questions'
      description: 'Searches for questions and returns the results as JSON. Access: PUB, USR, OWN, ADM'
      tags:
        - 'M03: Questions'
      
      parameters:
        - in: query
          name: text
          description: String to use for search
          schema:
            type: string
          required: false
        - in: query
          name: after
          description: Start date of the search interval
          schema:
            type: string
          required: false
        - in: query
          name: before
          description: End date of the search interval
          schema:
            type: string
          required: false

      responses:
        '200':
          description: 'Success.'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    content:
                      type: string
                    date:
                      type: string
                    file:
                      type: string
                    last_edited:
                      type: string
                    title:
                      type: string
                    user:
                      type: object
                      properties:
                        id:
                          type: integer
                        username:
                          type: string
                        image:
                          type: string
                example:
                  - id: 1
                    content: 'Healthcare has been changing rapidly. How can technology, especially emerging tech, improve the way healthcare is delivered?'
                    date: '2023-02-25'
                    file: null
                    last_edited: null
                    title: 'How Can Technology Improve Healthcare Delivery?'
                    id_user: 398
                    id_community: 20
                    tsvectors: "'chang':10B 'deliv':23B 'deliveri':6A 'emerg':16B 'especi':15B 'healthcar':5A,7B,21B 'improv':4A,18B 'rapid':11B 'tech':17B 'technolog':3A,14B 'way':20B"
                    likes_count: 0
                    dislikes_count: 0
                    answers_count: 0
                    user:
                      id: 398
                      username: 'nathanielstewart'
                      email: 'mirandachristopher@rivera.com'
                      register_date: '2019-11-05T00:00:00.000000Z'
                      administrator: false
                      blocked: false
                      image: 'https:\/\/picsum.photos\/250\/250'
                    community:
                      id: 20
                      name: 'Outdoors'
                    likes:
                    dislikes:
                    answers:

# M04: Answers

# Create Answer Action

  /answers:

    post:
      operationId: R401
      summary: 'R401: Create answer action'
      description: "Processes answer's creation form submission. Access: USR, OWN, ADM"
      tags:
        - 'M04: Answers'

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                content:
                  type: string
                  format: string
                id_question:
                  type: integer
                  format: integer
                id_user:
                  type: integer
                  format: integer
              required:
                - content
                - id_question
                - id_user
      
      responses:
        '302':
         description: 'Redirect after processing the answer submission.'
         headers:
           Location:
             schema:
               type: string
             examples:
               302Success:
                 description: 'Successful answer submission. Redirect to question page.'
                 value: '/questions/{id}'
        '403':
          description: 'This action is unauthorized.'

# Edit Answer

  /answers/{id}/:
  
    post:
        operationId: R402
        summary: 'R402: Edit answer action'
        description: 'Processes editions on an answer. Access: OWN, ADM'
        tags:
          - 'M04: Answers'

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

        requestBody:
          required: true
          content:
            application/x-www-form-urlencoded:
              schema:
                type: object
                properties:
                  content:
                    type: string
                    format: string
                required:
                  - content
    
        responses:
          '302':
            description: "Redirect after processing the edition on the answer."
            headers:
              Location:
                schema:
                  type: string
                examples:
                  302Success:
                    description: 'Successful edition. Redirect to question page.'
                    value: '/questions/{id}'
          '403':
            description: 'This action is unauthorized.'

# Delete Answer

  /answers/{id}/delete:

    post:
      operationId: R403
      summary: 'R403: Delete answer action'
      description: "Processes deletion of an answer. Access: OWN, ADM"
      tags:
        - 'M04: Answers'

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

      responses:
        '302':
          description: "Redirect after processing the deletion of the answer."
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: 'Successful deletion. Redirect to answer page.'
                  value: '/question{id}'
        '403':
          description: 'This action is unauthorized.'

# M05: Administration

# View Admin Page

  /admin:

      get:
        operationId: R501
        summary: 'R501: View admin page'
        description: 'Show admin page UI. Access: ADM'
        tags:
          - 'M05: Administration'

        responses:
          '200':
            description: 'OK. Show the admin page UI.'
          '403':
            description: 'This action is unauthorized.'

# Create User

  /users:
    
    post:
      operationId: R502
      summary: 'R502: Create user action'
      description: "Processes user's creation form submission. Access: ADM"
      tags:
        - 'M05: Administration'
      
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
                password_confirmation:
                  type: string
                  format: password
              required:
                - username
                - email
                - password
                - password_confirmation

      responses:
        '302':
          description: 'Redirect after processing the user credentials.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Successful user's creation. Redirect to admin page."
                  value: '/admin'
                302Failure:
                  description: "Failed user's creation. Redirect to admin page."
                  value: '/admin'
        '403':
          description: 'This action is unauthorized.'