openapi: 3.0.0

info:
  description: "The REST API for my demo e-commerce app, based on various herb and spice online shopping platforms."
  version: "1.0.0"
  title: "Mikayla's Spice Shop, REST API"

schemes: 
  - http

servers:
- url: localhost:8088/api
  description: The URL which currently hosts the REST API

host: localhost:4000

basePath: "/"

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
        password:
          type: string
        firstname?:
          type: string
        lastname?:
          type: string
    Product:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description?:
          type: string
        categoryid:
          type: integer
        regionid:
          type: integer
        price?:
          type: numeric
        inventory:
          type: integer
    Order:
      type: object
      properties:
        id:
          type: integer
        userid:
          type: integer
        total?:
          type: numeric
        delivered?:
          type: boolean
        processed?:
          type: boolean
        shipped?:
          type: boolean
    Cart:
      type: object
      properties:
        id:
          type: integer
        userid:
          type: integer
  securitySchemas:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: ''
          tokenUrl: ''
          scopes:
            read: ''
            write: ''
            admin: ''

tags:
  - name: admin
    description: "Platform management tools requiring administrative access."
  - name: auth
    description: "Handles user authentication workflows, including login and new user registration."
  - name: cart
    description: "Records for open 'cart' registries associated with user accounts"
  - name: orders
    description: "Carts become orders once payment has been processed. These orders are tracked here through their lifecycle, from order placement to delivery."
  - name: product
    description: "Records for each product in the store's registry, as well as associated data pertaining to pricing, inventory, etc."
  - name: user
    description: "Records for each user of the site, including relations to auth workflows, carts, and orders."

paths:
  /auth/register:
    post:
      summary: "New user registration"
      description: "Takes the request body and uses its data to create and insert a new user record into the database."
      tags:
        - auth
      produces:
        - "application/json"
      responses:
        201:
          description: "Request was successful"
          schema:
            type: object
        409:
          description: "An entry conflicting with this input already exists in the database."
          schema:
            type: object
  /auth/login:
    post:
      summary: "Login and get user account info"
      description: "Check the user input and, if it matches with the record in the database, login the user and open or update a user session."
      tags:
        - auth
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
      responses:
        200:
          description: "Successful login, returns user data from database"
        401:
          description: "Incorrect username or password"
          schema:
            type: object
  /auth/google:
    get:
      summary: "Authenticate current user through Google OAuth2"
      description: "Refers to external API verification of a user through the Google OAuth2 standard."
      tags:
        - auth
      produces:
        - "application/json"
      responses:
        200:
          description: "Google OAuth2 workflow successful"
          schema:
            type: object

  /cart/{userid}:
    get:
      summary: "Get the contents of a given user's cart"
      description: "For a given user, specified by the endpoint's {userid} parameter, get the data for this user's cart from the database."
      parameters:
        - name: userid
          in: path
          required: true
          description: "The user ID of the cart to be located, if it exists."
          schema:
            type: integer
            minimum: 1
      tags:
        - cart
      responses:
        200:
          description: "Cart located successfully"
          schema:
            $ref: '#/components/schemas/Cart'
        404:
          description: "Cart was not found"
          schema:
            type: object
    put:
      summary: "Update a given user's cart"
      description: "For a given user, specified by the endpoint's {userid} parameter, update that user's cart data to match the data specified in the request body."
      parameters:
        - name: userid
          in: path
          required: true
          description: "The user ID of the cart to be located, if it exists."
          schema:
            type: integer
            minimum: 1
      tags:
        - cart
      responses:
        201:
          description: "Cart update successful"
          schema:
            $ref: '#/components/schemas/Cart'
        400:
          description: "Bad request"
          schema:
            type: object
    delete:
      summmary: "Delete the record of a given cart"
      description: "ADMIN ACCESS REQUIRED. Deletes a given cart record by its cart ID"
      parameters:
        - name: cartid
          in: path
          required: true
          description: "The cart ID corresponding to the cart record to be deleted"
          schema:
            type: integer
            minimum: 1
      tags:
        - admin
      responses:
        204:
          description: "No content"
          schema:
            type: object
        403:
          description: "Proper authorization not provided"
          schema:
            type: object
    post:
      summary: "Insert a new cart record into the database"
      description: "Insert a new cart record into the database. Must correspond to an extant user id"
      tags:
        - cart
      responses:
        201:
          description: "Cart creation successful"
          schema:
            $ref: '#/components/schemas/Cart'
        500:
          descreiption: "Internal error"
          schema:
            type: object
  /orders:
    get:
      summary: "Get all records of all orders"
      description: ''
      tags:
        - orders
      responses:
        200:
          description: "Orders fetched successfully"
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Order'
    post:
      summary: "Post a new order record"
      description: "Open a new record for an order, associated with a user, in its default state, with additional details specified by the request body."
      tags:
        - orders
      responses:
        201:
          description: "Order creation successful"
          schema:
            $ref: '#/components/schemas/Order'
  /orders/{orderid}:
    get:
      summary: "Get one order by its order ID"
      parameters:
        - name: orderid
          in: path
          required: true
          description: "The order ID corresponding to the record to update"
          schema:
            type: integer
            minimum: 1
      tags:
        - orders
      responses:
        200:
          description: "Got order successfully"
          schema:
            $ref: '#/components/schemas/Order'
        404:
          description: "Order not found"
          schema:
            type: object
    delete:
      summary: "Delete an order by its order ID"
      description: "ADMIN ACCESS REQUIRED. Deletes a record from the database by its order ID"
      parameters:
        - name: orderid
          in: path
          required: true
          description: "The order ID corresponding to the record to update"
          schema:
            type: integer
            minimum: 1
      tags:
        - admin
  /product:
    get:
      summary: "Get all product listings"
      description: "Returns all product listings in the databases"
      tags:
        - product
      responses:
        200:
          description: "Got listings successfully"
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Product'
    post:
      summary: "Create a new product listing"
      description: "ADMIN ACCESS REQUIRED. Create a new product listing and insert it into the database"
      tags:
        - admin
      responses:
        201:
          description: "New product creation successful"
          schema:
            $ref: '#/components/schemas/Product'
        401:
          description: "Action unauthorized. Admin access required"
          schema:
            type: object
  /product/{productid}:
    get:
      summary: "Get one product listing by its product ID"
      parameters:
        - name: orderid
          in: path
          required: true
          description: "The order ID corresponding to the record to update"
          schema:
            type: integer
            minimum: 1
      tags:
        - product
      responses:
        200:
          description: "Got product listing successfully"
          schema:
            $ref: '#/components/schemas/Product'
    put:
      summary: "Update a product listing by its product ID"
      description: "ADMIN ACCESS REQUIRED. Find a record by its product ID and update its data by the request body."
      parameters:
        - name: orderid
          in: path
          required: true
          description: "The order ID corresponding to the record to update"
          schema:
            type: integer
            minimum: 1
      tags:
        - admin
      responses:
        200:
          description: "Product listing updated successfully."
          schema:
            $ref: '#/components/schemas/Product'
        401:
          description: "Access forbidden."
          schema:
            type: object
    delete:
      summary: "Delete a product listing by its product ID"
      description: "ADMIN ACCESS REQUIRED. Find a record by its product ID and delete it."
      parameters:
        - name: orderid
          in: path
          required: true
          description: "The order ID corresponding to the record to update"
          schema:
            type: integer
            minimum: 1
      tags:
        - admin
      responses:
        204:
          description: "Listing deleted successfully"
          schema:
            type: object
        401:
          description: "Access forbidden"
          schema:
            type: object

  /regions:
    get:
      summary: "Get all product regions"
      tags:
        - region
      responses:
        200:
          description: "Got region listing successfully"
          schema:
            type: object
        404:
          description: "Requested resource was not found"
          schema:
            type: object
  /regions/{regionid}:
    get:
      summary: "Get one region by its ID"
      tags:
        - region
      responses:
        200:
          description: "Got region listing successfully"
          schema:
            type: object
        404:
          description: "Requested resource was not found"
          schema:
            type: object

  /user:
    get:
      summary: "Get all users"
      tags:
        - user
  /user/{userid}:
    get:
      summary: "Get one user by a given user ID"
      tags:
        - user
    put:
      summary: "Update one user profile by its user ID"
      description: "Find one user's profile by user ID, and update its record using the request body"
      tags:
        - user
      responses:
        200:
          description: "User profile update OK"
          schema:
            type: object
        404:
          description: "User record not found"
          schema:
            type: object
    delete:
      summary: "Delete one user profile by its user ID"
      description: "ADMIN ACCESS REQUIRED. Find a user profile by its user ID and delete it from the database. THIS ACTION IS PERMANENT AND IRREVERSIBLE."
      tags:
        - admin
      responses:
        200:
          description: "User profile deletion successful"
          schema:
            type: object
        403:
          description: "Access forbidden"
          schema:
            type: object