---
# System prepended metadata

title: 'EAP: Architecture Specification and Prototype'

---

# EAP: Architecture Specification and Prototype

## A7: High-level architecture. Privileges. Web resources specification

The architecture of the web application to develop is documented indicating the catalogue of resources and the properties of each resource, including: references to the graphical interfaces, and the format of JSON responses. 

This page presents the documentation for Trade-a-Bid, including the following operations over data: create, read, update, and delete.

This specification adheres to the [OpenAPI](https://swagger.io/specification/) standard using YAML.

### 1. Overview

The modules that will be part of the application.  

| Module                                     | Description                                                                                                                                                                                                                                          |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| M01: Authentication and Individual Profile | Web resources associated with user authentication and individual profile management, includes the following system features: sign in/sign out, registration, credential recovery, viewing and editing personal information and change settings.      |
| M02: Auctions                              | Web resources associated with auctions, includes the following system features: auction listing and search, view and edit auction details, create and delete auctions, bookmark auctions.                                                            |
| M03: User                                  | Web resources associated with user, includes the following system features: user listing and search, view user profile, review user, follow user.                                                                                                    |
| M04: Administration                        | Web resources associated with user and auction management, includes the following system features: restrict and ban users, delete user accounts, edit and terminate auctions, change user information, and view system access details for each user. |
| M05: Other                                 | Web resources associated with general content of the website. Web resources with static content are associated with this module: About and FAQ.                                                                                                      |

### 2. Permissions

Permissions used by each module, necessary to access its data and features.  

<table>
<tbody>
  <tr>
    <td><span style="font-weight:bold">PUB</span></td>
    <td>Public</td>
    <td>Users without privileges</td>
  </tr>
  <tr>
    <td><span style="font-weight:bold">USR</span></td>
    <td>User</td>
    <td>Authenticated users</td>
  </tr>
  <tr>
    <td><span style="font-weight:bold">OWN</span></td>
    <td>Owner</td>
    <td>Owner</td>
  </tr>
  <tr>
    <td><span style="font-weight:bold">ADM</span></td>
    <td>Administrator</td>
    <td>Administrators</td>
  </tr>
</tbody>
</table>

### 3. OpenAPI Specification

This section includes the complete API specification in OpenAPI (YAML).

Additionally there is a link to the OpenAPI YAML file in the group's repository.

Also included is a link to the Swagger generated documentation (for easy navigation).

[Trade-a-Bid Open API specification in Gitlab repository](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/blob/master/openapi.yaml)
[Trade-a-Bid Open API specification in Swagger](https://app.swaggerhub.com/apis/lbaw2112/Trade-a-Bid/1.0)

```yaml
openapi: 3.0.0

info:
  version: "1.0"
  title: "Trade-a-Bid"
  description: "Web Resources Specification (A7) for Trade-a-Bid"

servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/lbaw2112/Trade-a-Bid/1.0
  - url: http://lbaw2112-piu.lbaw-prod.fe.up.pt/
    description: "Production server"

externalDocs:
  description: "Find more info here."
  url: https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/eap

tags:
  - name: "M01: Authentication and Individual Profile"
  - name: "M02: Auctions"
  - name: "M03: Users"
  - name: "M04: Administration"
  - name: "M05: Other"

paths:
  # M01: Authentication and Individual Profile
  /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 [UI04 Sign-in](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui04-sign-in)"

    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:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
              required:
                - email
                - password
      responses:
        "302":
          description: "Redirect after processing the login credentials."
          headers:
            location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Successful authentication, redirecting to home page"
                  value: "/"
                302Error:
                  description: "Failed to authenticate. Returning to login form"
                  value: "/login"

  /logout:
    post:
      operationId: R103
      summary: "R103: Sign-out"
      description: "Sign-out the current authenticated user. Access: USR, ADM"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "302":
          description: "Redict after processing sign-out"
          headers:
            location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Sign-out successful. Redirecting to home page"
                  value: "/"

  /register:
    get:
      operationId: R104
      summary: "R104: Register Form"
      description: "Provide a new user registration form. Access: PUB"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show [UI05 Sign-up](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui05-sign-up)"

    post:
      operationId: R105
      summary: "R105: Register new user"
      description: "Processes the form information to register new user. Access: PUB"
      tags:
        - "M01: Authentication and Individual Profile"

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                username:
                  type: string
                email:
                  type: string
                  format: email
                phone:
                  type: string
                  format: phone
                password:
                  type: string
                  format: password
                confirmationPassword:
                  type: string
                  format: password
                termsService:
                  type: boolean
              required:
                - name
                - username
                - email
                - phone
                - password
                - confirmationPassword
                - termsService

      responses:
        "302":
          description: "Redirect after processing new user information"
          headers:
            location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Sucessful registration. Redirecting to home page"
                  value: "/"
                302Error:
                  description: "Failed registration. Redirecting back to register form"
                  value: "/register"

  /users/me:
    get:
      operationId: R106
      summary: "R106: View your profile"
      description: "Show user's profile Access: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show [UI04 Sign-in](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui10-public-profile)"

  /user/settings_account:
    get:
      operationId: R107
      summary: "R107: Edit user profile"
      description: "Provide a form with the user's data to be edited. Access: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show [UI04 Sign-in](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui11-settings)"

    post:
      operationId: R108
      summary: "R108: Edit user profile"
      description: "Processes the form information to update user information. Acess: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                username:
                  type: string
                email:
                  type: string
                  format: email
                image:
                  type: string
                  format: binary
      responses:
        "302":
          description: 'Redirect after processing new account settings.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Account settings saved. Redirect to profile page."
                  value: "/user/{id}"
                302Failure:
                  description: "Couldn't save settings. Redirect to settings page."
                  value: "/user/settings_account"

  /user/settings_account/delete:
    post:
      operationId: R109
      summary: "R109: Delete account"
      description: "Deletes all your personal information and account"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "302":
          description: 'Redirect after processing account deletion.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Account deleted. Redirect to home page."
                  value: "/"
                302Failure:
                  description: "Couldn't delete account. Redirect to settings page."
                  value: "/user/settings_account"

  /user/settings_privacy:
    get:
      operationId: R110
      summary: "R110: Edit privacy settings"
      description: "Provide a form with the user's privacy settings to be edited. Access: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show [UI04 Sign-in](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui11-settings)"

    post:
      operationId: R111
      summary: "R111: Edit privacy settings"
      description: "Processes the form information to update user information. Acess: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                switch-nsf:
                  type: boolean
                switch-use-data:
                  type: boolean
                email:
                  type: string
                switch-notifications:
                  type: boolean
                switch-outbid-notifications:
                  type: boolean
                switch-start-auction-notifications:
                  type: boolean
                switch-user-activity-notifications:
                  type: boolean
      responses:
        "302":
          description: 'Redirect after processing privacy settings.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Privacy settings saved. Redirect to profile page."
                  value: "/user/{id}"
                302Failure:
                  description: "Couldn't save privacy settings. Redirect to profile page."
                  value: "/user/{id}"

  /user/settings_security:
    get:
      operationId: R112
      summary: "R112: Edit security settings"
      description: "Provide a form with passwords fields to be edited. Access: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show [UI04 Sign-in](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui11-settings)"

    post:
      operationId: R113
      summary: "R113: Edit security settings"
      description: "Processes the form information to update user's password. Acess: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                pwd:
                  type: string
                  format: password
                pwd-new:
                  type: string
                  format: password
                pwd-confirmed:
                  type: string
                  format: passowrd
      responses:
        "302":
          description: 'Redirect after processing security changes.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Security settings saved. Redirect to profile page."
                  value: "/user/{id}"
                302Failure:
                  description: "Couldn't save security settings. Redirect to profile page."
                  value: "/user/{id}"

  /user/dashboard/created_auctions:
    get:
      operationId: R114
      summary: "R114: View created acutions"
      description: "Show user's created auctions Access: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show [UI09 Dashboard](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui09-dashboard)"

  /user/dashboard/bidded_auctions:
    get:
      operationId: R115
      summary: "R115: View bidded acutions"
      description: "Show user's bidded auctions Access: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show [UI09 Dashboard](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui09-dashboard)"

  /user/dashboard/bookmarked_auctions:
    get:
      operationId: R116
      summary: "R116: View bookmarked acutions"
      description: "Show user's bookmarked auctions Access: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show [UI09 Dashboard](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui09-dashboard)"

  /user/dashboard/followed:
    get:
      operationId: R117
      summary: "R117: View followed users"
      description: "Show user's followed users Access: USR"
      tags:
        - "M01: Authentication and Individual Profile"
      responses:
        "200":
          description: "Ok. Show [UI09 Dashboard](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui09-dashboard)"

  # M02: Auctions

  /auction/create_auction:
    get:
      operationId: R201
      summary: "R201: Create auction form"
      description: "Provide a new auction registration form. Access: USR"
      tags:
        - "M02: Auctions"
      responses:
        "200":
          description: "Ok. Show [UI08 Create Auction](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui08-create-auction)"

    post:
      operationId: R202
      summary: "R202: Create an auction"
      description: "Processes the form information to create an auction. Access: USR"
      tags:
        - "M02: Auctions"

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                startDate:
                  type: string
                  format: date
                startTime:
                  type: string
                  format: time
                endDate:
                  type: string
                  format: date
                endTime:
                  type: string
                  format: time
                startingBid:
                  type: number
                increment:
                  type: number
                isPercentual:
                  type: boolean
                category:
                  type: string
                nsfw:
                  type: boolean
                images:
                  type: array
                  items:
                    type: string
                    format: binary
              required:
                - name
                - description
                - startDate
                - startTime
                - endDate
                - endTime
                - startingBid
                - increment
                - isPercentual
                - category
                - nsfw
                - images

      responses:
        "302":
          description: 'Redirect after processing the new auction information.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Auction created successfully. Redirect to auction page."
                  value: "/auctions/{id}"
                302Failure:
                  description: "Auction couldn't be created. Redirect to create auction form."
                  value: "/auction/create_auction"

  /auction/{id}:
    get:
      operationId: R203
      summary: "R203: View an auction"
      description: "Show auction page. Access: PUB"
      tags:
        - "M02: Auctions"
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
      responses:
        "200":
          description: "Ok. Show [UI07 Auction](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui07-auction)"

  /auction/search_results:
    get:
      operationId: R204
      summary: "R204: Search Auctions"
      description: "Searches for auctions and returns the search results as JSON. Access: PUB"
      tags:
        - "M02: Auctions"
      parameters:
        - in: query
          name: category
          description: "Categories to search for"
          schema:
            type: array
            items:
              type: string
          required: false
        - in: query
          name: min_bid_value
          description: "Minimum value for the current bid of an auction"
          schema:
            type: number
            format: money
          required: false
        - in: query
          name: max_bid_value
          description: "Maximum value for the current bid of an auction"
          schema:
            type: number
            format: money
          required: false
        - in: query
          name: followed_users
          description: "Boolean with the flag to search for followed users"
          schema:
            type: boolean
          required: false
        - in: query
          name: status
          description: "Specific auction status, i.e. Open and/or Scheduled auctions"
          schema:
            type: array
            items:
              type: string
          required: false
        - in: query
          name: username
          description: "Search for specific usernames"
          schema:
            type: string
          required: false
        - in: query
          name: search_text
          description: "String to use for full-text search"
          schema:
            type: string
          required: false
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string
                    seller:
                      type: string
                    current_bid:
                      type: number
                      format: money
                    personal_bid:
                      type: number
                      format: money
                    start_date:
                      type: string
                      format: date
                    end_date:
                      type: string
                      format: date
                    bookmarked:
                      type: boolean
                    thumb_image:
                      type: string
                      format: binary
                    status:
                      type: string
              example:
                - id: 1
                  title: "Foo Fighters - Greatest Hits MP3"
                  seller: "ffighters"
                  current_bid: 125.3
                  personal_bid: 123.59
                  start_date: "2021-03-13 12:00:00"
                  end_date: "2021-03-27 12:00:00"
                  bookmarked: true
                  thumb_image: image
                  status: "Open"
                - id: 6
                  title: "Fighters Legacy - STEAM KEY"
                  seller: "ppenguin"
                  current_bid: 103.03
                  personal_bid: null
                  start_date: "2021-02-12 12:00:00"
                  end_date: "2021-03-20 12:00:00"
                  bookmarked: false
                  thumb_image: image
                  status: "Open"

  /auction/{id}/delete:
    get:
      operationId: R205
      summary: "R205: Delete an auction"
      description: "Set specified auction as 'Terminated'. Access: USR"
      tags:
        - "M02: Auctions"
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
      responses:
        "200":
          description: "Ok. Show [UI09 Dashboard](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui09-dashboard)"

  /auction/{id}/edit:
    get:
      operationId: R206
      summary: "R206: Edit auction form."
      description: "Fetch edit auction form. Access: USR"
      tags:
        - "M02: Auctions"
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
      responses:
        "200":
          description: "Ok. Show [UI07 Auction](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui07-auction)"

    post:
      operationId: R207
      summary: "R207: Edit an auction"
      description: "Processes the form information to edit an auction. Access: OWN"
      tags:
        - "M02: Auctions"
      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
                description:
                  type: string
                start_date:
                  type: string
                  format: date
                start_time:
                  type: string
                  format: time
                end_date:
                  type: string
                  format: date
                end_time:
                  type: string
                  format: time
                starting_bid:
                  type: number
                increment:
                  type: number
                category:
                  type: string
                nsfw:
                  type: boolean
              required:
                - name
                - description
                - start_date
                - start_time
                - end_date
                - end_time
                - starting_bid
                - increment
                - category
                - nsfw

      responses:
        "302":
          description: 'Redirect after processing the new auction information.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Auction created successfully. Redirect to auction page."
                  value: "/"
                302Failure:
                  description: "Auction couldn't be created. Redirect to create auction form."
                  value: "/auctions/create_auction"

  /auction/{id}/report:
    get:
      operationId: R208
      summary: "R208: Show report auction form."
      description: "Fetch report auction form. Access: USR"
      tags:
        - "M02: Auctions"
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
      responses:
        "200":
          description: "Ok. Show [UI07 Auction](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui07-auction)"

    post:
      operationId: R209
      summary: "R209: Save report data"
      description: "Processes the form information to report an auction. Access: USR"
      tags:
        - "M02: Auctions"

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  format: category
                description:
                  type: string
              required:
                - reason
                - description

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

      responses:
        "302":
          description: 'Redirect after processing the report information.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Auction reported. Redirect to auction page."
                  value: "/auction/{id}"
                302Failure:
                  description: "Couldn't report auction. Redirect to report auction form."
                  value: "/auction/{id}"

  /auction/{id}/bid:
    post:
      operationId: R210
      summary: "R210: Auction bid"
      description: "R210: Bid on an auction. Access: USR"
      tags:
        - "M02: Auctions"

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

      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                value:
                  type: integer
                bidder_id:
                  type: integer
              required:
                - value
                - bidder_id
      responses:
        "302":
          description: 'Redirect after processing the bid.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Auction reported. Redirect to auction page."
                  value: "/auction/{id}"
                302Failure:
                  description: "Couldn't report auction. Redirect to auction page."
                  value: "/auction/{id}"

  /auction/{id}/bookmark:
    post:
      operationId: R211
      summary: "Set Bookmark"
      description: "R211: Mark auction as bookmarked. Access: USR"
      tags:
        - "M02: Auctions"
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
      responses:
        '200':
          description: OK
        default:
          description: Unexpected error

    delete:
      operationId: R212
      summary: "Unset Bookmark"
      description: "R212: Unmark auction as bookmarked. Access: USR"
      tags:
        - "M02: Auctions"
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
      responses:
        '200':
          description: OK
        default:
          description: Unexpected error
            
  # M03: Users
  /users/{username}:
    get:
      operationId: R301
      summary: "R301: User profile"
      description: "Shows a user profile. Access: PUB"
      tags:
        - "M03: Users"
      parameters:
        - in: path
          name: username
          schema:
            type: string
          required: true
      responses:
        "200":
          description: "Ok. Show [UI10 Public Profile](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui10-public-profile)"

  /users/search_results:
    get:
      operationId: R302
      summary: "R302: Search Users"
      description: "Searches for users and returns the search results as JSON. Access: PUB"
      tags:
        - "M03: Users"
      parameters:
        - in: query
          name: has_auctions
          description: "Search only for users who have auctions"
          schema:
            type: boolean
          required: false
        - in: query
          name: followed_users
          description: "Boolean indicating if only followed users should be displayed"
          schema:
            type: boolean
          required: false
        - in: query
          name: min_rating
          description: "Minimum value for a user's rating"
          schema:
            type: integer
          required: false
        - in: query
          name: max_rating
          description: "Maximum value for a user's rating"
          schema:
            type: integer
          required: false
        - in: query
          name: min_register_date
          description: "Minimum account creation date"
          schema:
            type: string
            format: date
          required: false
        - in: query
          name: max_register_date
          description: "Maximum account creation date"
          schema:
            type: string
            format: date
          required: false
        - in: query
          name: sort
          description: "Sorted items by"
          schema:
            type: string
        - in: query
          name: search_text
          description: "String to use for full-text search"
          schema:
            type: string
          required: false
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    username:
                      type: string
                    profile_image:
                      type: string
                      format: binary
                    joined:
                      type: string
                      format: date
                    followed:
                      type: boolean
                    rating:
                      type: integer
              example:
                - id: 4
                  name: "Old Monk"
                  username: "old_monk"
                  profile_image: image
                  joined: "2021-04-15 16:00:00"
                  followed: true
                  rating: 56
                - id: 9
                  name: "Farm Worker"
                  username: "ppenguin"
                  profile_image: image
                  joined: "2021-03-01 15:30:00"
                  followed: false
                  rating: 343

  /users/{username}/follow:
    put:
      operationId: R303
      summary: "R303: Follow user"
      description: "Follow a user. Access: USR"
      tags:
        - "M03: Users"
      parameters:
        - in: path
          name: username
          schema:
            type: string
          required: true
      responses:
        "200":
          description: "Ok. Success"

    delete:
      operationId: R304
      summary: "R304: Unfollow user"
      description: "Unfollow a user. Access: USR"
      tags:
        - "M03: Users"
      parameters:
        - in: path
          name: username
          schema:
            type: string
          required: true
      responses:
        "200":
          description: "Ok. Success"

  /users/{username}/report:
    post:
      operationId: R305
      summary: "R305: Report user"
      description: "Report a user. Access: USR"
      tags:
        - "M03: Users"
      parameters:
        - in: path
          name: username
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  format: category
                description:
                  type: string
              required:
                - reason
                - description
      responses:
        "302":
          description: 'Redirect after processing the report information.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "User reported. Redirect to auction page."
                  value: "/users/{username}"
                302Failure:
                  description: "Couldn't report user. Redirect to report user form."
                  value: "/users/{username}"

  /users/{username}/rate:
    put:
      operationId: R306
      summary: "R306: Rate user"
      description: "Rate a user. Access: USR"
      tags:
        - "M03: Users"
      parameters:
        - in: path
          name: username
          schema:
            type: string
          required: true
      responses:
        "200":
          description: "Ok. Success"
    delete:
      operationId: R307
      summary: "R307: Remove user rating"
      description: "Remove user rating. Access: USR"
      tags:
        - "M03: Users"
      parameters:
        - in: path
          name: username
          schema:
            type: string
          required: true
      responses:
        "200":
          description: "Ok. Success"

  # M04 Administration
  /admin/user_management:
    get:
      operationId: R401
      summary: "R401: Manage banned users"
      description: "Displays banned users to be managed by an administrator. Access: ADM"
      tags:
        - "M04: Administration"
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    username:
                      type: string
                    permissions:   # boolean?
                      type: array
                      items:
                        type: boolean
                    reason:
                      type: string
                      format: category
                    joined:
                      type: string
                      format: date
              example:
                - id: 5
                  username: "markhamill"
                  permissions:
                    - true
                    - false
                    - false
                  reason: "Fraudulent Behaviour"
                  joined: "2021-04-15 16:00:00"
                - id: 7
                  username: "johndoe"
                  permissions:
                    - false
                    - false
                    - true
                  reason: "Fraudulent Behaviour"
                  joined: "2021-04-15 17:00:00"

    post:
      operationId: R402
      summary: "R402: Change User Permissions"
      description: "Change Permissions. Access: ADM"
      tags:
        - "M04: Administration"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                user_id:
                  type: integer
                permissions:
                  type: array
                  items:
                    type: boolean
              required:
                - user_id
                - permissions
      responses:
        "302":
          description: 'Redirect after processing permissions.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Permissions changed."
                  value: "/dashboard_admin/user_management"
                302Failure:
                  description: "Couldn't change permissions."
                  value: "/dashboard_admin/user_management"

  /admin/reported_users:
    get:
      operationId: R403
      summary: "R403: View reported users"
      description: "Displays all reported users. Access: ADM"
      tags:
        - "M04: Administration"
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    username:
                      type: string
                    reason:
                      type: string
                      format: category
                    details:
                      type: string
                    date:
                      type: string
                      format: date
              example:
                - id: 5
                  username: "markhamill"
                  reason: "Fraudulent Behaviour"
                  details: "Improper username"
                  date: "2021-02-12 17:00:00"
                - id: 7
                  username: "johndoe"
                  reason: "Fraudulent Behaviour"
                  details: "Improper profile image"
                  date: "2021-04-15 18:00:00"

  /admin/auction_management:
    get:
      operationId: R404
      summary: "R404: Manage reported auctions"
      description: "Displays all auctions to be managed by an administrator. Access: ADM"
      tags:
        - "M04: Administration"
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string
                    status:
                      type: string
                    details:
                      type: string
                    start_date:
                      type: string
                      format: date
                    end_date:
                      type: string
                      format: date
              example:
                - id: 5
                  title: "Siksong Steam Key"
                  status: "Active"
                  details: "Attempt to sell unreleased game"
                  start_date: "2021-02-12 17:00:00"
                  end_date: "2021-02-14 17:00:00"
                - id: 7
                  title: "Hades Steam Key"
                  status: "Active"
                  details: "Using images from other games"
                  start_date: "2021-02-14 12:00:00"
                  end_date: "2021-02-15 12:00:00"
    post:
      operationId: R405
      summary: "R405: Change auction status"
      description: "Change auction status. Access: ADM"
      tags:
        - "M04: Administration"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                auction_id:
                  type: integer
                status:
                  type: string
              required:
                - auction_id
                - status
      responses:
        "302":
          description: 'Redirect after processing status.'
          headers:
            Location:
              schema:
                type: string
              examples:
                302Success:
                  description: "Changed auction status."
                  value: "/dashboard_admin/auction_management"
                302Failure:
                  description: "Couldn't change auction status."
                  value: "/dashboard_admin/auction_management"

  /admin/reported_auctions:
    get:
      operationId: R406
      summary: "R406: View all reported auctions"
      description: "Displays all auction reports. Access: ADM"
      tags:
        - "M04: Administration"
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string
                    reason:
                      type: string
                      format: category
                    details:
                      type: string
                    date:
                      type: string
                      format: date
              example:
                - id: 5
                  title: "Siksong Steam Key"
                  reason: "Fraudulent Behaviour"
                  details: "Attempt to sell unreleased game"
                  date: "2021-02-12 17:00:00"
                - id: 4
                  title: "Hades Steam Key"
                  reason: "Improper auction pictures"
                  details: "Using images from other games"
                  date: "2021-02-15 12:00:00"

  # M05: Other
  /:
    get:
      operationId: R501
      summary: "R501: Display Home page"
      description: "R501: Display Home page"
      tags:
        - "M05: Other"
      responses:
        "200":
          description: "Ok. Show [UI01 Home](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui01-home)"

  /faq:
    get:
      operationId: R502
      summary: "R502: Display FAQ page"
      description: "Display faq page. Access: PUB"
      tags:
        - "M05: Other"
      responses:
        "200":
          description: "Ok. Show [UI03 FAQ](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui03-faq)"

  /about:
    get:
      operationId: R503
      summary: "R503: Display About page"
      description: "Display about page. Access: PUB"
      tags:
        - "M05: Other"
      responses:
        "200":
          description: "Ok. Show [UI02 About](https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112/-/wikis/er#ui02-about)"
```

---


## A8: Vertical prototype

The Vertical Prototype includes the implementation of two or more user stories (the simplest) and aims to validate the architecture presented, also serving to gain familiarity with the technologies used in the project.

The implementation is based on the [LBAW Framework](https://git.fe.up.pt/lbaw/template-laravel) and include work on all layers of the architecture of the solution to implement: user interface, business logic and data access. The prototype includes the implementation of pages of visualization, insertion, edition and removal of information; the control of permissions in the access to the implemented pages; and a presentation of error and success messages.

### 1. Implemented Features

#### 1.1. Implemented User Stories

User stories that were implemented in the prototype.  

| User Story reference | Name                         | Priority | Description                                                                                                                                                            |
| -------------------- | ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| US001                | See Home                     | High     | As a *User*, I want to access the home page, so I can have a general view of the website                                                                               |
| US005                | View auction                 | High     | As a *User*, I want to check auctions' information, so that I'm informed in greater detail about it                                                                    |
| US006                | View user profile            | High     | As a *User*, I want to check a user's profile, so that I'm informed about their rating, name, description, and auctions                                                |
| US007                | See About                    | Medium   | As a *User*, I want to access the About page, so I can see the website's complete description                                                                          |
| US008                | See Contact                  | Medium   | As a User, I want to access contacts about the system's maintainers, so that I can report any technical issues and give feedback                                       |
| US010                | See FAQ                      | Low      | As a *User*, I want to access the FAQ, so that I can see the frequently asked questions to clarify common issues                                                       |
| US012                | View auction bidding history | Low      | As a User, I want to check the bidding history of a certain auction, so I can analyze the growth of the bids and plan ahead                                            |
| US101                | Sign-up                      | High     | As a *Guest*, I want to register a new account, so I can authenticate myself                                                                                           |
| US102                | Sign-in                      | High     | As a *Guest*, I_ want to authenticate into the system, so that I access privileged information and participate in auctions                                             |
| US201                | See Dashboard                | High     | As an Authenticated Member, I want to have access to a personal dashboard, so I can easily access my resources (such as followed users, bookmarked auctions,  etc... ) |
| US204                | Report auction               | High     | As an Authenticated Member, I want to report auctions, so the platform is kept free from fraudulent or indecent auctions                                               |
| US207                | Sign-out                     | High     | As an *Authenticated Member*, I want to log out from the system, so that my session is terminated                                                                      |
| US208                | Consult bookmarked auctions  | High     | As an *Authenticated Member*, I want to consult my bookmarked auctions, so that I can easily remember what auctions I saved                                            |
| US209                | Consult bidding history      | High     | As an Authenticated Member, I want to consult previous auctions I bid on, so that I can easily revisit them                                                            |
| US210                | Consult auctions history     | High     | As an *Authenticated Member*, I want to consult previous auctions I created, so that I can easily revisit them                                                         |
| US213                | Follow User                  | Medium   | As an *Authenticated Member*, I want to follow a user, so that I can reach their profile easier and stay informed about their auctions                                 |
| US214                | Unfollow User                | Medium   | As an *Authenticated Member*, I want to unfollow a user, so that I'm no longer notified about their activity                                                           |
| US303                | Bookmark add                 | High     | As a *Bidder*, I want to add auctions to my bookmarks, so I can easily keep track of their updates                                                                     |
| US304                | Bookmark remove              | High     | As a *Bidder*, I want to remove auctions from my bookmarks, so I can stop keeping track of their updates                                                               |
| US401                | Create an auction            | High     | As a *Seller*, I want to create an auction, so that I can sell my product                                                                                              |
| US402                | Set base price for auction   | High     | As a *Seller*, I want to set the base price for an auction, so the product doesn't get lowballed                                                                       |
| US403                | Delete auction               | High     | As a *Seller*, I want to delete an auction, so that it isn't available anymore                                                                                         |
| US404                | Schedule auctions            | Medium   | As a Seller, I want to schedule auctions for my items, so I can inform possible buyers beforehand                                                                      |
| US506                | Sign-out                     | High     | As an *Admin*, I want to log out from the system, so that my session is terminated                                                                                     |

#### 1.2. Implemented Web Resources

Web resources that were implemented in the prototype.  

> Module M01: Authentication and Individual Profile

| Web Resource Reference     | URL                                 |
| -------------------------- | ----------------------------------- |
| R101: Login Form           | /login                              |
| R102: Login Action         | /POST/login                         |
| R103: Logout               | logout                              |
| R104: Register Form        | /register                           |
| R105: Register Action      | /POST/register                      |
| R106: View your profile    | /users/me                           |
| R114: Dashboard Created    | /user/dashboard/created_auctions    |
| R115: Dashboard Bidded     | /user/dashboard/bidded_auctions     |
| R116: Dashboard Bookmarked | /user/dashboard/bookmarked_auctions |

> Module M02: Auctions

| Web Resource Reference      | URL                          |
| --------------------------- | ---------------------------- |
| R201: Create Auction        | /auction/create_auction      |
| R202: Create Auction Action | /POST/auction/create_auction |
| R203: View an Auction       | /auction/{id}                |
| R206: Edit Auction Form     | /auction/{id}/edit           |
| R207: Edit Auction Action   | /POST/auction/{id}/edit      |
| R208: Report Auction Form   | /auction/{id}/report         |
| R209: Report Auction Action | /POST/auction/{id}/report    |
| R211: Bookmark              | /POST/auction/{id}/bookmark  |
| R212: Delete an Auction     | /auction/{id}/delete         |

> Module M03: Users

| Web Resource Reference  | URL                      |
| ----------------------- | ------------------------ |
| R301: View User Profile | /users/{username}        |
| R303: Follow User       | /users/{username}/follow |

> Module M05: Other

| Web Resource Reference | URL    |
| ---------------------- | ------ |
| R501: Home page        | /      |
| R502: FAQ              | /faq   |
| R503: About            | /about |

### 2. Prototype

The prototype is available at http://lbaw2112-piu.lbaw-prod.fe.up.pt/

#### Credentials

**Admin user:** Terunosuke_Miyamoto@jojo.com/zawarudo
**Regular user:** skelo@jojo.com/gizzard

The code is available at https://git.fe.up.pt/lbaw/lbaw2021/lbaw2112

---

## Revision history

Changes made to the first submission:

- None so far

***

GROUP2112, 03/05/2021

* Eduardo Correia, up201806433@fe.up.pt (Editor)
* Ivo Saavedra, up201707093@fe.up.pt
* Telmo Baptista, up201806554@fe.up.pt
* Tiago Silva, up201806516@fe.up.pt
