a7_openapi.yaml

openapi: 3.0.0

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

servers:
- url: https://lbaw2261.lbaw.fe.up.pt
  description: Production server
- url: localhost:8000
  description: Localhost server

tags:
  - name: 'M01: Authentication and Individual Profile'
  - name: 'M02: Feed'
  - name: 'M03: Groups'
  - name: 'M04: Requests'
  - name: 'M05: Messages'
  - name: 'M06: Notifications'
  - name: 'M07: Search'
  - name: 'M08: User Administration and Static pages'


paths:

  /:
      get:
          operationId: R201
          summary: "R201: Website root redirect to home"
          description: "Website root. Access: PUB"
          tags:
            - "M02: Feed"
            
          responses:
            "302":
              description: "Redirect to home"
              headers:
                Location:
                  schema:
                    type: string
                  examples:
                    302:
                      description: "Redirect to home"
                      value: "/home"   

  /login:
    get:
      operationId: R101
      summary: "R101: Login Form"
      description: "Provide login form. Access: PUB"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200": 
          description: "Ok. Show log-in UI05"
    post:
      operationId: R102
      summary: "R102: Login Action"
      description: "Processes the login form submission. Access: PUB"
      tags:
        - "M01: Authentication and Individual Profile"

      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: "/home" 
                302Error:
                  description: "Failed authentication. Redirect to login form."
                  value: "/login"


  /logout:
    get:
      operationId: R103
      summary: "R103: Logout Action"
      description: "Logout the current authenticated user. Access: USR, ADM"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "302":
          description: "Redirect after processing logout."
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Successful logout. Redirect to login form."
                  value: "/login"
        
  /register:
    get:
      operationId: R104
      summary: "R104: Register Form"
      description: "Provide new user registration form. Access: PUB"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show sign-up UI"

    post:
      operationId: R105
      summary: "R105: Register Action"
      description: "Processes the Register form submission. Access: PUB"
      tags:
        - "M01: Authentication and Individual Profile"

      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
                username: # <!--- form field name
                  type: string
                birthdate: # <!--- form field name
                  type: string
                bio: # <!--- form field name
                  type: string
              required:
                - email
                - password
                - username
                - birthdate

      responses:
        "302":
          description: "Redirect after processing the register credentials."
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Successful register. Redirect to user profile."
                  value: "/home"
                302Error:
                  description: "Failed to register. Redirect to register form."
                  value: "/register"

  /about:
    get:
      operationId: R801
      summary: "R801: About Page"
      description: "Show Nexus About page. Access: PUB"
      tags:
        - "M08: User Administration and Static pages"

      responses:
        "302":
          description: "Ok. Show about page UI"
        "404":
          description: "Page not available"

  /contacts:
    get:
      operationId: R802
      summary: "R802: Contacts Page"
      description: "Show Nexus Contact page. Access: PUB"
      tags:
        - "M08: User Administration and Static pages"

      responses:
        "302":
          description: "Ok. Show contacts page UI"
        "404":
          description: "Page not available"

  /admin:
    get:
      operationId: R803
      summary: "R803: Admin Page"
      description: "Show administrator page. Access: ADM"
      tags:
        - "M08: User Administration and Static pages"

      responses:
        "302":
          description: "Ok. Show admin UI"
        "404": 
          description: "Page not available"

  /features:
    get:
      operationId: R804
      summary: "R804: Main Features Page"
      description: "Show Nexus Feature page. Access: PUB"
      tags:
        - "M08: User Administration and Static pages"

      responses:
        "302":
          description: "Ok. Show features page UI"
        "404":
          description: "Page not available"

  /home: 
    get:
      operationId: R202
      summary: 'R202 View Home Page'
      description: 'Show the home page Access: PUB'
      tags:
        - "M02: Feed"
      responses:
        '200':
          description: 'Ok. Show home page UI' 


  /404:
    get:
      operationId: R805
      summary: "R805: Not Found Page"
      description: "Show Nexus Not Found page. Access: PUB"
      tags:
        - "M08: User Administration and Static pages"

      responses:
        "302":
          description: "Ok. Show features page UI"
        "404":
          description: "Page not available"


  /post/{id}:
    get:
      operationId: R203
      summary: 'R203: View Post Page'
      description: 'Shows post, with comments, likes etc. Access: PUB/USR'
      tags:
        - "M02: Feed"

      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          
      responses:
        '200':
          description: 'Ok, show Post Page UI02'
        '403':
          description: 'Forbidden access to resource, the post might be private or it does not exists'


  /profile/{username}:
    get:
      operationId: R106
      summary: 'R106: Profile page'
      description: 'Show the profile page . Access: PUB/USR'
      tags:
        - 'M01: Authentication and Individual Profile'

      parameters:
        - in: path
          name: username
          schema:
            type: string
          required: true

      responses:
        '200':
          description: 'Ok. Show profile page'
        '404':
            description: 'Profile not found' 
   

  /group/{name}:
    get:
       operationId: R301
       summary: 'R301: Group Profile page'
       description: 'Group Profile. Access: PUB/USR'
       tags:
        - "M03: Groups"
       parameters:
       - in: path
         name: name
         schema:
           type: string
         required: true
       responses:
        '200':
          description: 'Success. Show group page'
        '404': 
          description: 'Group Profile does not exist'
   

  /search/{query}:
    get:
      operationId: R701
      summary: "R701: Search"
      description: "Show Search hits page. Access: PUB"
      tags:
        - "M07: Search"

      parameters:
        - in: query
          name: query
          description: 'Queried String'
          schema: 
            type: string
          required: true

      responses:
        "302":
          description: "Ok. Show search page" 


  /messages/{sender_username}:
    get:
      operationId: R501
      summary: 'R501 View message page'
      description: 'Show the messages page UI04. Access: USR'
      tags:
        - "M05: Messages"
      responses:
        '200':
          description: 'Ok. Show message page'
        '403':
          description: 'Forbidden access to resource'
        '404':
          description: 'Not found'


  /api/post/feed/{type_feed}: 
    get:
      operationId: R204
      summary: 'R204 Get Posts'
      description: 'Gets the posts according to the parameters and returns the results as json Access: USR and PUB for viral'
      tags:
        - "M02: Feed"
      parameters:
        - in: path
          name: type_feed
          description: 'Filter parameter. Can be "for_you", "friends", "groups", "viral" '
          schema:
            type: string
          required: true
    
      responses:
        '200':
          description: 'Success'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    text:
                      type: string
                    post_date:
                      type: string 
                    owner:
                      type: string
                    photo:
                      type: string
                    likes_count:
                      type: integer
                    comments_count:
                      type: integer
                    ranking:
                      type: number
                    images:
                      type: array
                      items:
                        type: string
                    hasLiked:
                      type: boolean
                    isOwner:
                      type: boolean
                    auth:
                      type: integer

                
                example:
                  - id: 123
                    text: "The dark side of the force is stronger!!!"
                    post_date: "2022-05-04 22:22:22"
                    owner: Darth Vader
                    photo: user/1.png
                    likes_count: 10
                    comments_count: 5
                    ranking: 4.1292965
                    images:
                      - post/666.png
                      - post/667.png
                    hasLiked: true
                    isOwner: false
                    auth: 0
                    



  /api/search/{query_string}/type/{type_search}: 
    get:
      operationId: R702
      summary: "R702: Search API"
      description: "Searches for works and returns the results as JSON. Access: PUB."

      tags:
        - "M07: Search"

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

        - in: query
          name: type_search
          description: Filter parameter. Can be "users", "groups", "posts" or "topics".
          schema:
            type: string
          required: true


      responses:
        "200":
          description: Json Search Results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object # It can be users, groups, posts or topics
                        
  /api/group:
    post:
      operationId: R302
      summary: 'R302: Create a Group'
      description: 'Creates a Group. Access: USR'
      tags:
        - "M03: Groups"
      requestBody:
        required: true
        content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    description:
                      type: string 
                    visibility:  
                      type: integer
                    image:
                      type: string
                      format: binary
                        
      responses:
        '201':
          description: 'The group was created successfully'
        '400':
          description: 'There is something wrong with the request body'


  /api/group/{name}: 
    post:
      operationId: R303
      summary: 'R303: Edit a Group'
      description: 'Edit a Group'
      tags:
      - "M03: Groups"
      parameters:
      - in: path
        name: name
        schema:
          type: string
        required: true
      
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
             type: object
             properties:
               name:
                 type: string
               description:
                 type: string
               visibility:
                  type: boolean
               picture:
                 type: string
                 format: binary
      responses:
        '200':
          description: 'The group was edit successfully'
        '403':
          description: 'Forbidden access to resource, the Group is not yours'
          
    delete:
      operationId: R304
      summary: 'R304: Delete Group'
      description: 'Deletes a group. Access: USR'
      tags:
      - "M03: Groups"
      parameters: 
      - in: path
        name: name_group
        schema:
          type: string
        required: true
      responses:
        '200':
          description: 'The group was deleted successfully'
        '403':
          description: 'Forbidden access to resource, the group is not yours'


  /api/profile/{username}:
    post: 
        operationId: R107
        summary: 'R107: Edit a Profile'
        description: 'Edit a Profile'
        tags:
          - "M01: Authentication and Individual Profile"
        parameters:
        - in: path
          name: username
          schema:
            type: string
          required: true
        requestBody:
          required: true
          content:
            multipart/form-data:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  email:
                    type: string
                  password:
                      type: string 
                  visibility:
                      type: boolean  
                  bio:
                      type: string
                  picture:
                    type: string
                    format: binary
        responses:
          '200':
            description: 'The profile was edit successfully'
          '403':
            description: 'Forbidden access to resource, the profile is not yours'
                      
    delete:
      operationId: 'R108'
      summary: 'R108: Delete a Profile'
      description: 'Deletes a profile. Access: USR'
      tags:
        - "M01: Authentication and Individual Profile"
      parameters: 
      - in: path
        name: username
        schema:
          type: string
        required: true
      responses:
        '200':
          description: 'The profile was deleted successfully'
        '403':
          description: 'Forbidden access to resource, the profile is not yours'


  /api/group_member/{id}:
    get: 
      operationId: R305
      summary: 'R305: Get group member'
      description: 'Get group member. Access: USR'
      tags:
        - "M03: Groups"
        
      parameters:
       - in: path
         name: id
         schema:
           type: integer
         required: true
        
      responses:
        '200':
          description: 'The group members were returned successfully'
        '403':
          description: 'Forbidden access to resource'
  
    delete: 
      operationId: R306
      summary: 'R306: Delete group member'
      description: 'Delete group member from group with id. Access: OWN'
      tags:
        - "M03: Groups"
        
      parameters:
       - in: path
         name: id
         schema:
           type: integer
         required: true
         
      responses:
        '200':
          description: 'The group member was deleted successfully'
        '403':
          description: 'Forbidden access to resource'

/api/group/{name}/owner/{id}:
    post: 
      operationId: R307
      summary: 'R307: Promote a Member'
      description: 'Promote a member: OWN'
      tags:
        - "M03: Groups"

      parameters:
       - in: path
         name: id
         schema:
           type: integer
         required: true
         
      responses:
        '200':
          description: 'The group member was promoted successfully'
        '403':
          description: 'Forbidden access to resource'     

 /api/post/{id}:       
    delete:
      operationId: R205
      summary: 'R205: Delete Post'
      description: 'Deletes a post. Access: OWN'
      tags:
        - "M02: Feed"
      parameters: 
       - in: path
         name: id
         schema:
           type: integer
         required: true
      responses:
        '200':
          description: 'The post was deleted successfully'
        '403':
          description: 'Forbidden access to resource, the post is not yours'
          
    post: 
      operationId: R206
      summary: 'R206: Edit a Post'
      description: 'Edit a post. Access: OWN'
      tags:
        - "M02: Feed"
         
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
             type: object
             properties:
               text:
                 type: string
               picture:
                 type: array
                 items:
                  type: string
                  format: binary
             required:
                 - text
      responses:
        '200':
          description: 'The post was edit successfully'
        '403':
          description: 'Forbidden access to resource, the post is not yours'

/api/admin/pendent_reports/{query_string}:
     get:
      operationId: 'R806'
      summary: 'R806 Get the pendent reports'
      description: 'Get the pendent reports. Access: ADM'
      tags:
        - "M08: User Administration and Static pages"
    
      parameters:
       - in: path
         name: query_string
         schema:
           type: string
         required: true        

      responses:
  
        '200':
          description: 'Success'
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: object
                  properties:
                    id: 
                      type: integer
                    username:
                      type: string
                    photo:
                      type: string
                    ban_date:
                      type: string
                    decision_date:
                      type: string

        '403':
          description: 'Forbidden'

/api/admin/past_reports/{query_string}:
    get:
      operationId: 'R807'
      summary: 'R807 Get the past reports'
      description: 'Get the past reports. Access: ADM'
      tags:
        - "M08: User Administration and Static pages"
      
      parameters:
       - in: path
         name: query_string
         schema:
           type: string
         required: true
      
      responses:
        '200':
          description: 'Success'
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: object
                  properties:
                    id: 
                      type: integer
                    username:
                      type: string
                    photo:
                      type: string
                    ban_date:
                      type: string
                    decision_date:
                      type: string
                      
        '403':
          description: 'Forbidden'

/api/like_post:
    post:
      operationId: 'R207'
      summary: 'R207 Toggle like on post'
      description: 'Toggle like on post. Access: USR'
      tags:
        - "M02: Feed"
      
      requestBody:
        required: true
        content:
            application/json:
              schema:
                type: object
                properties:
                  id_user:
                    type: integer
                  id_post:
                    type: integer 

      responses:
        '200':
          description: 'The like was sucessful'
        '403':
          description: 'Forbidden access to resource'

/api/like_comment:
    post:
      operationId: 'R208'
      summary: 'R208 Toggle like on comment'
      description: 'Toggle like on comment. Access: USR'
      tags:
        - "M02: Feed"
        
      requestBody:
        required: true
        content:
            application/json:
              schema:
                type: object
                properties:
                  id_user:
                    type: integer
                  id_comment:
                    type: integer 

      responses:
        '200':
          description: 'The like was sucessful'
        '403':
          description: 'Forbidden access to resource'

/api/post:
    post:
      operationId: R209
      summary: 'R209: Create a Post'
      description: 'Creates a post. Access: USR'
      tags:
        - "M02: Feed"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                text:
                  type: string
                group:
                  type: string
                picture: 
                  type: array
                  items:
                    type: string
                    format: binary
              required:
                - text

      responses:
        '201':
          description: 'The post was created successfully'
        '400':
          description: 'There is something wrong with the request body'