a7_openapi.yml

openapi: 3.0.0

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

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

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

tags:
 - name: 'M01: Authentication'
 - name: 'M02: Individual Profile'
 - name: 'M03: Posts'
 - name: 'M04: Comments'
 - name: 'M05: User Administration'
 - name: 'M06: Post Administration'
 - name: 'M07: Comment Administration'
 - name: 'M08: Static Pages'

paths:
 /login:
   get:
     operationId: R101
     summary: 'R101: Login Form'
     description: 'Provide login form. Access: PUB'
     tags:
       - 'M01: Authentication'
     responses:
       '200':
         description: 'Ok. Show Log-in 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:
               email:          # <!--- form field name
                 type: string
               password:    # <!--- form field name
                 type: string
             required:
                  - email
                  - password

     responses:
       '302':
         description: 'Redirect after processing the login credentials.'
         headers:
           Location:
             schema:
               type: string
             examples:
               302Success:
                 description: 'Successful authentication. Redirect to user profile.'
                 value: '/users/{id}'
               302Error:
                 description: 'Failed authentication. Redirect to login form.'
                 value: '/login'

 /logout:

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

 /register:
   get:
     operationId: R104
     summary: 'R104: Register Form'
     description: 'Provide new user registration form. Access: PUB'
     tags:
       - 'M01: Authentication'
     responses:
       '200':
         description: 'Ok. Show Sign-Up UI'

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

     requestBody:
       required: true
       content:
         application/x-www-form-urlencoded:
           schema:
             type: object
             properties:
               name:
                 type: string
               email:
                 type: string
               username:
                 type: string
               password:
                 type: string
               birthday:
                 type: string
                 format: date
                 description: 'Birthday of user'
                 example: '30-01-2022'
             required:
                - name
                - email
                - username
                - password
                - birthday

     responses:
       '302':
         description: 'Redirect after processing the new user information.'
         headers:
           Location:
             schema:
               type: string
             examples:
               302Success:
                 description: 'Successful authentication. Redirect to user profile.'
                 value: '/users/{id}'
               302Failure:
                 description: 'Failed authentication. Redirect to login form.'
                 value: '/register'

 /users/{id}:
   get:
     operationId: R201
     summary: 'R201: View user profile'
     description: 'Show the individual user profile. Access: PUB'
     tags:
       - 'M02: Individual Profile'

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

     responses:
       '200':
         description: 'Ok. Show User Profile UI'

 /users/{id}/edit:
   get:
     operationId: R202
     summary: 'R202: Show edit user form'
     description: 'Show the individual user profile editing page. Access: OWR'
     tags:
       - 'M02: Individual Profile'

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

     responses:
       '200':
         description: 'Ok. Show User Profile Edit UI'
   patch:
    operationId: R203
    summary: 'R203: Process show edit user form'
    description: 'Process the individual user profile editing information. Access: OWR'
    tags:
      - 'M02: Individual Profile'
    parameters:
       - in: path
         name: id
         schema:
           type: integer
         required: true
    responses:
      '302':
        description: 'Redirect after processing the edit information back to the user page.'
        headers:
          Location:
            schema:
              type: string

 /users/{id}/questions:
   get:
     operationId: R204
     summary: 'R204: View user own questions'
     description: 'Show the individual user questions. Access: PUB'
     tags:
       - 'M02: Individual Profile'

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

     responses:
       '200':
         description: 'Ok. Show User Questions UI'
         
 /users/{id}/answers:
   get:
     operationId: R205
     summary: 'R205: View user own answers'
     description: 'Show the individual user answers. Access: PUB'
     tags:
       - 'M02: Individual Profile'

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

     responses:
       '200':
         description: 'Ok. Show User Answers UI'

 /api/users/{id}:
  delete:
    operationId: R206
    summary: 'R206: Delete User Account'
    description: 'Delete the account. Access: USR, ADM'
    tags:
      - 'M02: Individual Profile'
    parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
    responses:
      '302':
        description: 'Ok. Show login UI'
         
 /posts/{id}:
   get:
     operationId: R301
     summary: 'R301: View post'
     description: 'Show the post. Access: PUB'
     tags:
       - 'M03: Posts'

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

     responses:
       '200':
         description: 'Ok. Show Post UI'
  
 /posts/questions/new:
   get:
    operationId: R302
    summary: 'R302: Add Question Form'
    description: 'Provide new question form. Access: USR'
    tags:
      - 'M03: Posts'

    parameters:
      - in: path
        name: userId
        schema:
          type: integer
        required: true
    
    responses:
       '200':
         description: 'Ok. Show Add Question UI'
    
   post:
    operationId: R303
    summary: 'R303: Add Question Action'
    description: 'Processes the new question form submission. Access: USR'
    tags:
      - 'M03: Posts'

    requestBody:
      required: true
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              title:
                type: string
              postText:
                type: string
            required:
               - title
               - postText

    responses:
      '302':
        description: 'Redirect after processing the new question information.'
        headers:
          Location:
            schema:
              type: string

 /posts/answers/new:
   get:
    operationId: R304
    summary: 'R304: Add Answer Form'
    description: 'Provide new answer form. Access: USR'
    tags:
      - 'M03: Posts'

    parameters:
      - in: path
        name: userId
        schema:
          type: integer
        required: true
      - in: path
        name: postId
        schema:
          type: integer
        required: true
    
    responses:
       '200':
         description: 'Ok. Show Add Answer UI'
    
   post:
    operationId: R305
    summary: 'R305: Add Answer Action'
    description: 'Processes the new answer form submission. Access: USR'
    tags:
      - 'M03: Posts'

    requestBody:
      required: true
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              postText:
                type: string
            required:
               - postText

    responses:
      '302':
        description: 'Redirect after processing the new answer information.'
        headers:
          Location:
            schema:
              type: string
 
 /posts/{id}/edit:
   get:
    operationId: R306
    summary: 'R306: Edit Post Form'
    description: 'Provide edit post form. Access: OWR'
    tags:
      - 'M03: Posts'

    parameters:
      - in: query
        name: title
        schema:
          type: integer
        required: false
      - in: query
        name: postText
        schema:
          type: integer
        required: false
    
    responses:
       '200':
         description: 'Ok. Show Edit Post UI'

   patch:
    operationId: R307
    summary: 'R307: Edit Post Action'
    description: 'Provide edit post form. Access: OWR'
    tags:
      - 'M03: Posts'
    
    parameters:
      - in: query
        name: postText
        schema:
          type: integer
        required: false
    
    responses:
      '302':
        description: 'Redirect after processing edit post information.'
        headers:
          Location:
            schema:
              type: string


 /homepage:
  get:
    operationId: R308
    summary: 'R308: Show homepage'
    description: 'Show all posts indiscriminately. Access: PUB'
    tags:
      - 'M03: Posts'
    responses:
       '200':
         description: 'Ok. Show HomePage UI'
  post:
    operationId: R309
    summary: 'R309: Show search results'
    description: 'Processes the search and displays the results. Access: PUB'
    tags:
      - 'M03: Posts'
    requestBody:
      required: true
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              search:
                type: string
              tags:
                type: string
              searchfor:
                type: string
              orderby:
                type: string
            required:
               - searchfor
               - orderby
    responses:
      '302':
        description: 'Redirect after processing the search.'
        headers:
          Location:
            schema:
              type: string
              
 /api/posts/{id}:
   delete:
     operationId: R310
     summary: 'R310: Delete a post API'
     description: 'Delete a post. Access: OWR, ADM'
     tags:
       - 'M03: Posts'

     parameters:
       - in: path
         name: userId
         schema:
           type: integer
         required: true
       - in: path
         name: postId
         schema:
           type: integer
         required: true
         
     responses:
       '302':
         description: 'Ok. Show Post UI'

 /api/star/{userId}/{postId}:
   get:
     operationId: R311
     summary: 'R311: Show star'
     description: 'Show if star is active in a post. Access: USR'
     tags:
       - 'M03: Posts'

     parameters:
       - in: path
         name: userId
         schema:
           type: integer
         required: true
       - in: path
         name: postId
         schema:
           type: integer
         required: true
     
     responses:
       '200':
         description: 'Ok. Show Post UI'
         
   put:
     operationId: R312
     summary: 'R312: Like a post API'
     description: 'Put a star in a post. Access: USR'
     tags:
       - 'M03: Posts'

     parameters:
       - in: path
         name: userId
         schema:
           type: integer
         required: true
       - in: path
         name: postId
         schema:
           type: integer
         required: true
         
     responses:
       '302':
         description: 'Ok. Show Post UI'
         
   delete:
     operationId: R313
     summary: 'R313: Unlike a post API'
     description: 'Delete star in a post. Access: USR'
     tags:
       - 'M03: Posts'

     parameters:
       - in: path
         name: userId
         schema:
           type: integer
         required: true
       - in: path
         name: postId
         schema:
           type: integer
         required: true
         
     responses:
       '302':
         description: 'Ok. Show Post UI'

         
 /comments/{id}:
   get:
     operationId: R401
     summary: 'R401: View comment'
     description: 'Show the comment. Access: PUB'
     tags:
       - 'M04: Comments'

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

     responses:
       '200':
         description: 'Ok. Show Comment UI'
         
 /about:
   get:
     operationId: R801
     summary: 'R801: View about page'
     description: 'Show the about page. Access: PUB'
     tags:
       - 'M08: Static Pages'
       
     responses:
       '200':
         description: 'Ok. Show About UI'

 /contacts:
   get:
     operationId: R802
     summary: 'R802: View contacts page'
     description: 'Show the contacts page. Access: PUB'
     tags:
       - 'M08: Static Pages'
       
     responses:
       '200':
         description: 'Ok. Show Contacts UI'
  
 /faq:
   get:
     operationId: R803
     summary: 'R803: View faqs page'
     description: 'Show the faqs page. Access: PUB'
     tags:
       - 'M08: Static Pages'
       
     responses:
       '200':
         description: 'Ok. Show FAQs UI'