api-spec.yaml

openapi: 3.0.3
info:
  title: Codecademy Ecommerce App API
  version: 1.0.0
  description: The API of a fake (independent practice project) ecommerce app.
  contact:
    name: Chris Mastris
    url: https://github.com/Cmastris/ecommerce-pern-app
paths:
  /auth/status:
    summary: Used to retrieve the current user's authentication status.
    get:
      summary: Retrieves the current user's authentication status.
      description: >-
        Retrieves a summary of the current user's authentication (logged in) status,
        including their account details if logged in.
      operationId: get_auth_status
      responses:
        '200':
          description: A success response containing the authentication summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthStatus'
      tags:
        - auth
  /auth/register:
    summary: Used to register for an account.
    post:
      summary: Creates a new user account.
      description: >-
        Creates a new user account based on a provided username and password, if
        the provided username does not already exist.
      operationId: create_account
      requestBody:
        required: true
        description: A user registration object (email address and password).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRegistration'
      responses:
        '201':
          description: A success response containing the newly created user data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetails'
        '400':
          description: A user with the provided username already exists.
      tags:
        - auth
  /auth/login:
    summary: Used to log in to an account (authenticate); required for some endpoints.
    post:
      summary: Logs in to an existing user account.
      description: >-
        Logs in to a user account using the provided username and password
        credentials.
      operationId: login
      requestBody:
        required: true
        description: A user credentials object (email address as 'username' and password).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCredentials'
      responses:
        '200':
          description: A success response containing the user data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetails'
        '401':
          description: The provided credentials (username or password) are incorrect.
      tags:
        - auth
  /auth/logout:
    summary: Used to log out of the current user account.
    post:
      summary: Logs out of the current user account.
      description: ''
      operationId: logout
      responses:
        '200':
          description: A success response indicating that the user is logged out.
      tags:
        - auth
  /users/{id}:
    summary: Used to retrieve and modify a user's account details.
    parameters:
      - in: path
        name: id
        required: true
        description: The user id.
        schema:
          type: integer
    get:
      summary: Retrieves a user's account details.
      description: ''
      operationId: get_user
      responses:
        '200':
          description: A success response containing the user data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetails'
        '401':
          description: The logged in user doesn't have permission to access this user's details.
      tags:
        - users
    put:
      summary: Updates the user's password.
      description: ''
      operationId: update_user
      requestBody:
        required: true
        description: An object containing the new password.
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
      responses:
        '200':
          description: A success response.
        '401':
          description: The logged in user doesn't have permission to access this user's details.
      tags:
        - users
  /products:
    summary: Used to retrieve the details of multiple products.
    get:
      summary: Retrieves the details of multiple products.
      description: 'Retrieves the details of multiple products, optionally filtering all products by either category ID or by a search term.'
      operationId: get_products
      parameters:
        - in: query
          name: category_id
          required: false
          description: A category id to filter products by (optional).
          schema:
            type: integer
        - in: query
          name: search_term
          required: false
          description: A case insensitive search term to filter products by, based on the search term's inclusion within the product name (optional).
          schema:
            type: string
      responses:
        '200':
          description: A success response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfProductDetails'
      tags:
        - products
  /products/{id}:
    summary: Used to retrieve the details of a single product.
    parameters:
      - in: path
        name: id
        required: true
        description: The product id.
        schema:
          type: integer
    get:
      summary: Retrieves the details of a single product.
      description: ''
      operationId: get_product
      responses:
        '200':
          description: A success response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetails'
        '404':
          description: The product ID doesn't exist.
      tags:
        - products
  /categories:
    summary: Used to retrieve the details of multiple categories.
    get:
      summary: Retrieves the details of multiple categories.
      description: ''
      operationId: get_categories
      responses:
        '200':
          description: A success response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfCategoryDetails'
      tags:
        - categories
  /cart:
    summary: Used to retrieve all items from the logged in user's cart.
    get:
      summary: Retrieves all items from the logged in user's cart.
      description: ''
      operationId: get_cart
      responses:
        '200':
          description: A success response containing the cart items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfCartItems'
        '401':
          description: The cart can't be accessed because the user isn't logged in.
      tags:
        - cart
  /cart/items/{product_id}:
    summary: Used to add and delete user cart items.
    parameters:
      - in: path
        name: product_id
        required: true
        description: The product id.
        schema:
          type: integer
    post:
      summary: Adds a product to the logged in user's cart.
      description: ''
      operationId: add_cart_product
      parameters:
        - in: query
          name: quantity
          required: false
          description: The product quantity (optional; defaults to 1).
          schema:
            type: integer
      responses:
        '201':
          description: A success response containing the new cart item details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartItem'
        '400':
          description: Invalid request. The requested quantity is greater than the available quantity or the product is already in the user's cart.
        '401':
          description: The cart can't be accessed because the user isn't logged in.
        '404':
          description: The product ID doesn't exist.
      tags:
        - cart
    delete:
      summary: Deletes a product from the logged in user's cart.
      description: ''
      operationId: delete_cart_product
      responses:
        '204':
          description: A success response indicating that the cart item was deleted or didn't exist.
        '401':
          description: The cart can't be accessed because the user isn't logged in.
      tags:
        - cart
  /orders:
    summary: Used to retrieve a summary of all previous orders by the logged in user.
    get:
      summary: Retrieves a summary of all previous orders by the logged in user.
      description: ''
      operationId: get_orders
      responses:
        '200':
          description: A success response containing the orders summary data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfOrderSummaryItems'
        '401':
          description: Orders can't be accessed because the user isn't logged in.
      tags:
        - orders
  /orders/{id}:
    summary: Used to retrieve the details of a single previous order.
    parameters:
      - in: path
        name: id
        required: true
        description: The order id.
        schema:
          type: integer
    get:
      summary: Retrieves the details of a single previous order.
      description: ''
      operationId: get_order
      responses:
        '200':
          description: A success response containing the order details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetails'
        '401':
          description: The user isn't logged in as the user who made the order.
        '404':
          description: The order ID doesn't exist.
      tags:
        - orders
    delete:
      summary: Cancels a pending order.
      description: Cancels an order if its current status is 'pending'.
      operationId: cancel_order
      responses:
        '204':
          description: A success response indicating that the order is cancelled.
        '400':
          description: Invalid request. The order does not have a status of 'pending'.
        '401':
          description: The user isn't logged in as the user who made the order.
        '404':
          description: The order ID doesn't exist.
      tags:
        - orders
components:
  schemas:
    AuthStatus:
      type: object
      properties:
        logged_in:
          type: boolean
        id:
          type: integer
          nullable: true
        email_address:
          type: string
          nullable: true
        auth_method:
          type: string
          nullable: true
    UserRegistration:
      type: object
      properties:
        email_address:
          type: string
        password:
          type: string
    UserCredentials:
      type: object
      properties:
        username:
          type: string
          description: The user's email address.
        password:
          type: string
    UserDetails:
      type: object
      properties:
        id:
          type: integer
        email_address:
          type: string
    ProductDetails:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: string
        available_stock_count:
          type: integer
        short_description:
          type: string
        long_description:
          type: string
        avg_rating:
          type: string
        rating_count:
          type: integer
    ArrayOfProductDetails:
      type: array
      items:
        $ref: '#/components/schemas/ProductDetails'
    CategoryDetails:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        url_slug:
          type: string
    ArrayOfCategoryDetails:
      type: array
      items:
        $ref: '#/components/schemas/CategoryDetails'
    CartItem:
      type: object
      properties:
        product_id:
          type: integer
        product_name:
          type: string
        product_price:
          type: string
        product_quantity:
          type: integer
    ArrayOfCartItems:
      type: array
      items:
        $ref: '#/components/schemas/CartItem'
    OrderItem:
      type: object
      properties:
        product_id:
          type: integer
        product_name:
          type: string
        product_price:
          type: string
        product_quantity:
          type: integer
    OrderDetails:
      type: object
      properties:
        order_id:
          type: integer
        user_id:
          type: integer
        order_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        order_placed_time:
          type: string
        order_status:
          type: string
        total_cost:
          type: string
        address:
          type: string
        postcode:
          type: string
    OrderSummaryItem:
      type: object
      properties:
        order_id:
          type: integer
        order_placed_time:
          type: string
        order_status:
          type: string
        total_cost:
          type: string
    ArrayOfOrderSummaryItems:
      type: array
      items:
        $ref: '#/components/schemas/OrderSummaryItem'