Skip to content

API Documentation

Jump to bottom
KellyAnneSantos edited this page Jan 18, 2023 · 3 revisions

API Documentation

USER AUTHENTICATION/AUTHORIZATION

All endpoints that require authentication

All endpoints that require a current user to be logged in.

  • Request: endpoints that require authentication

  • Error Response: Require authentication

    • Status Code: 401

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Authentication required",
  "statusCode": 401
}

All endpoints that require proper authorization

All endpoints that require authentication and the current user does not have the correct role(s) or permission(s).

  • Request: endpoints that require proper authorization

  • Error Response: Require proper authorization

    • Status Code: 403

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Forbidden",
  "statusCode": 403
}

Get the Current User

Returns the information about the current user that is logged in.

  • Require Authentication: true

  • Request

    • Method: GET
    • URL: /users/current
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "firstName": "John",
  "lastName": "Smith",
  "fakeName": "Jack",
  "email": "john.smith@gmail.com",
  "phone": "0123456789"
  "previewImage": "https://t3.ftcdn.net/jpg/03/58/90/78/360_F_358907879_Vdu96gF4XVhjCZxN2kCG0THTsSQi8IhT.jpg",
}

Log In a User

Logs in a current user with valid credentials and returns the current user's information.

  • Require Authentication: false

  • Request

    • Method: POST

    • URL: /login

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "credential": "john.smith@gmail.com",
  "password": "secret password"
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@gmail.com",
  "phone": "0123456789"
}

  • Error Response: Invalid credentials

    • Status Code: 401

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Invalid credentials",
  "statusCode": 401
}

  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "statusCode": 400,
  "errors": {
    "credential": "Email or phone is required",
    "password": "Password is required"
  }
}

Sign Up a User

Creates a new user, logs them in as the current user, and returns the current user's information.

  • Require Authentication: false

  • Request

    • Method: POST

    • URL: /signup

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@gmail.com",
  "phone": "0123456789",
  "password": "secret password"
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@gmail.com",
  "phone": "0123456789",
}

  • Error response: User already exists with the specified email

    • Status Code: 403

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "User already exists",
  "statusCode": 403,
  "errors": {
    "email": "User with that email already exists"
  }
}

  • Error response: User already exists with the specified phone

    • Status Code: 403

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "User already exists",
  "statusCode": 403,
  "errors": {
    "phone": "User with that phone already exists"
  }
}

  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "statusCode": 400,
  "errors": {
    "email": "Invalid email",
    "phone": "Phone is required",
    "firstName": "First Name is required",
    "lastName": "Last Name is required"
  }
}

PRODUCTS

Get all Products

Returns all the products.

  • Require Authentication: true

  • Request

    • Method: GET
    • URL: /products
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "Products": [
    {
      "id": 1,
      "merchantId": 1,
      "name": "Garment Steamer",
      "department": "Home",
      "price": 21.27,
      "description": "Place where web developers are created",
      "freeReturn": true,
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36",
      "avgRating": 4.5,
      "previewImage": "image url",
    }
  ]
}

Get all Products owned by the Current User

Returns all the products owned (created) by the current user.

  • Require Authentication: true

  • Request

    • Method: GET
    • URL: /users/current/products
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "Products": [
    {
      "id": 1,
      "merchantId": 1,
      "name": "Garment Steamer",
      "department": "Home",
      "price": 21.27,
      "description": "Place where web developers are created",
      "freeReturn": true,
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36",
      "avgRating": 4.5,
      "previewImage": "image url",
    }
  ]
}

Get details of a Product from an id

Returns the details of a product specified by its id.

  • Require Authentication: true

  • Request

    • Method: GET
    • URL: /products/:productId
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

          {
      "id": 1,
      "merchantId": 1,
      "name": "Garment Steamer",
      "department": "Home",
      "price": 21.27,
      "description": "Place where web developers are created",
      "freeReturn": true,
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36",
      "avgRating": 4.5,
      "previewImage": "image url",
  "Descriptions": [
    {
      "id": 1,
      "productId": 1,
      "merchantId": 1,
      "bulletPoint": "test"
    }
  ],
  "User": {
    "id": 1,
    "firstName": "John",
    "lastName": "Smith",
    "fakeName": "Jack",
    "email": "demo@user.io",
    "phone": "0123456789",
    "previewImage": "test",
  },
  "Review": {
    "id": 1,
    "userId": 1,
    "productId": 1,
    "stars": 5,
    "headline": "test",
    "previewImage": "test",
    "body": "test",
  }
  "Question": {
    "id": 1,
    "userId": 1,
    "productId": 1,
    "body": "test",
  }
}

  • Error response: Couldn't find a Product with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Product couldn't be found",
  "statusCode": 404
}

Create a Product

Creates and returns a new product.

  • Require Authentication: true

  • Request

    • Method: POST

    • URL: /spots

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "merchantId": 1,
  "name": "Garment Steamer",
  "department": "Home",
  "price": 21.27,
  "description": "test",
  "freeReturn": true,
  "prime": true,
  "previewImage": "test",
}

  • Successful Response

    • Status Code: 201

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "merchantId": 1,
  "name": "Garment Steamer",
  "department": "Home",
  "price": 21.27,
  "description": "test",
  "freeReturn": true,
  "prime": true,
  "previewImage": "test",
}

  • Error Response: Body validation error

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation Error",
  "statusCode": 400,
  "errors": {
    "name": "Product name is required and must be between 2 and 255 characters",
    "department": "Department must be an existing department",
    "price": "Price is invalid",
    "description": "Description is required and must be 255 characters or less",
    "previewImage": "Preview image is required and must be between 5 and 255 characters",
  }
}

Add an Image to a Product based on the Product's id

Create and return a new image for a product specified by id.

  • Require Authentication: true

  • Require proper authorization: Product must belong to the current user

  • Request

    • Method: POST

    • URL: /products/:productId/images

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "url": "image url"
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "imageableId": 1,
  "url": "image url"
}

  • Error response: Couldn't find a Product with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Product couldn't be found",
  "statusCode": 404
}

Edit a Product

Updates and returns an existing product.

  • Require Authentication: true

  • Require proper authorization: Product must belong to the current user

  • Request

    • Method: PUT

    • URL: /products/:productId

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "merchantId": 1,
  "name": "Garment Steamer",
  "department": "Home",
  "price": 21.27,
  "description": "test",
  "freeReturn": true,
  "prime": true,
  "previewImage": "test",
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "merchantId": 1,
  "name": "Garment Steamer",
  "department": "Home",
  "price": 21.27,
  "description": "test",
  "freeReturn": true,
  "prime": true,
  "previewImage": "test",
}

  • Error Response: Body validation error

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation Error",
  "statusCode": 400,
  "errors": {
    "name": "Product name is required and must be between 2 and 255 characters",
    "department": "Department must be an existing department",
    "price": "Price is invalid",
    "description": "Description is required and must be 255 characters or less",
    "previewImage": "Preview image is required and must be between 5 and 255 characters",
  }
}

  • Error response: Couldn't find a Product with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Product couldn't be found",
  "statusCode": 404
}

REVIEWS

Get all Reviews of the Current User

Returns all the reviews written by the current user.

  • Require Authentication: true

  • Request

    • Method: GET
    • URL: /users/current/reviews
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "Reviews": [
    {
      "id": 1,
      "userId": 1,
      "productId": 1,
      "review": "This was an awesome spot!",
      "stars": 5,
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36",
      "User": {
        "id": 1,
        "firstName": "John",
        "lastName": "Smith",
        "fakeName": "Smith",
        "email": "demo@user.io",
        "phone": "01234556789",
        "previewImage": "test",
      },
      "Images": [
        {
          "id": 1,
          "imageableId": 1,
          "url": "image url"
        }
      ]
    }
  ]
}

Get all Reviews by a Product's id

Returns all the reviews that belong to a product specified by id.

  • Require Authentication: false

  • Request

    • Method: GET
    • URL: /products/:productId/reviews
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "Reviews": [
    {
      "id": 1,
      "userId": 1,
      "spotId": 1,
      "review": "This was an awesome spot!",
      "stars": 5,
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36",
      "User": {
        "id": 1,
        "firstName": "John",
        "lastName": "Smith",
        "fakeName": "Smith",
        "email": "demo@user.io",
        "phone": "01234556789",
        "previewImage": "test",
      },
      "Images": [
        {
          "id": 1,
          "imageableId": 1,
          "url": "image url"
        }
      ]
    }
  ]
}

  • Error response: Couldn't find a Product with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Product couldn't be found",
  "statusCode": 404
}

Create a Review for a Product based on the Product's id

Create and return a new review for a product specified by id.

  • Require Authentication: true

  • Request

    • Method: POST

    • URL: /products/:productId/reviews

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "review": "This was an awesome product!",
  "stars": 5
}

  • Successful Response

    • Status Code: 201

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "userId": 1,
  "productId": 1,
  "review": "This was an awesome product!",
  "stars": 5,
  "createdAt": "2021-11-19 20:39:36",
  "updatedAt": "2021-11-19 20:39:36"
}

  • Error Response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "statusCode": 400,
  "errors": {
    "review": "Review text is required",
    "stars": "Stars must be an integer from 1 to 5"
  }
}

  • Error response: Couldn't find a Product with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Product couldn't be found",
  "statusCode": 404
}

  • Error response: Review from the current user already exists for the Product

    • Status Code: 403

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "User already has a review for this product",
  "statusCode": 403
}

Add an Image to a Review based on the Review's id

Create and return a new image for a review specified by id.

  • Require Authentication: true

  • Require proper authorization: Review must belong to the current user

  • Request

    • Method: POST

    • URL: /reviews/:reviewId/images

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "url": "image url"
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "imageableId": 1,
  "url": "image url"
}

  • Error response: Couldn't find a Review with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Review couldn't be found",
  "statusCode": 404
}

  • Error response: Cannot add any more images because there is a maximum of 10 images per resource

    • Status Code: 403

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Maximum number of images for this resource was reached",
  "statusCode": 403
}

Edit a Review

Update and return an existing review.

  • Require Authentication: true

  • Require proper authorization: Review must belong to the current user

  • Request

    • Method: PUT

    • URL: /reviews/:reviewId

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "review": "This was an awesome product!",
  "stars": 5
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "userId": 1,
  "productId": 1,
  "review": "This was an awesome product!",
  "stars": 5,
  "createdAt": "2021-11-19 20:39:36",
  "updatedAt": "2021-11-20 10:06:40"
}

  • Error Response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "statusCode": 400,
  "errors": {
    "review": "Review text is required",
    "stars": "Stars must be an integer from 1 to 5"
  }
}

  • Error response: Couldn't find a Review with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Review couldn't be found",
  "statusCode": 404
}

Delete a Review

Delete an existing review.

  • Require Authentication: true

  • Require proper authorization: Review must belong to the current user

  • Request

    • Method: DELETE
    • URL: /reviews/:reviewId
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Successfully deleted",
  "statusCode": 200
}

  • Error response: Couldn't find a Review with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Review couldn't be found",
  "statusCode": 404
}

ORDERS

Get all of the Current User's Orders

Return all the orders that the current user has made.

  • Require Authentication: true

  • Request

    • Method: GET
    • URL: /users/current/orders
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "Orders": [
    {
      "id": 1,
      "userId": 1,
      "status": "ordered",
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36"
    }
  ]
}

Create an Order for a Product based on the Product's id

Create and return a new order for a product specified by id.

  • Require Authentication: true

  • Request

    • Method: POST

    • URL: /users/current/productorders

    • Body:

      {
  "productId": 1,
  "quantity": 1
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "productId": 1,
  "orderId": 2,
  "quantity": 1,
  "createdAt": "2021-11-19 20:39:36",
  "updatedAt": "2021-11-19 20:39:36"
}

  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "statusCode": 400,
  "errors": {
    "quantity": "Quantity is invalid"
  }
}

  • Error response: Couldn't find a Product with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Product couldn't be found",
  "statusCode": 404
}

Edit a ProductOrder

Update and return an existing productOrder.

  • Require Authentication: true

  • Require proper authorization: ProductOrder must belong to the current user

  • Request

    • Method: PUT

    • URL: /productorders/:productOrderId

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "quantity": 1,
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "productId": 1,
  "orderId": 2,
  "quantity: 1,
  "createdAt": "2021-11-19 20:39:36",
  "updatedAt": "2021-11-20 10:06:40"
}

  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "statusCode": 400,
  "errors": {
    "quantity": "Quantity is invalid"
  }
}

  • Error response: Couldn't find a ProductOrder with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Product order couldn't be found",
  "statusCode": 404
}

Delete a ProductOrder

Delete an existing productorder.

  • Require Authentication: true

  • Require proper authorization: ProductOrder must belong to the current user

  • Request

    • Method: DELETE
    • URL: /productorders/:productOrderId
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Successfully deleted",
  "statusCode": 200
}

  • Error response: Couldn't find a ProductOrder with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Product order couldn't be found",
  "statusCode": 404
}

IMAGES

Delete an Image

Delete an existing image.

  • Require Authentication: true

  • Require proper authorization: Image must belong to the current user

  • Request

    • Method: DELETE
    • URL: /images/:imagesId
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Successfully deleted",
  "statusCode": 200
}

  • Error response: Couldn't find an Image with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Image couldn't be found",
  "statusCode": 404
}

Add Query Filters to Get All Products

Return products filtered by query parameters.

  • Require Authentication: true

  • Request

    • Method: "GET",
    • URL: "/products"
    • Query Parameters
      • page: integer, minimum: 0, maximum: 10, default: 0
      • size: integer, minimum: 0, maximum: 500000, default: 500000
      • minPrice: decimal, optional, minimum: 0
      • maxPrice: decimal, optional, minimum: 0
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "Spots": [
    {
      "id": 1,
      "merchantId": 1,
      "name": "Garment Steamer",
      "department": "Home",
      "price": 21.27,
      "description": "Place where web developers are created",
      "freeReturn": true,
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36",
      "avgRating": 4.5,
      "previewImage": "image url",
  "Descriptions": [
    {
      "id": 1,
      "productId": 1,
      "merchantId": 1,
      "bulletPoint": "test"
    }
  ],
  "User": {
    "id": 1,
    "firstName": "John",
    "lastName": "Smith",
    "fakeName": "Jack",
    "email": "demo@user.io",
    "phone": "0123456789",
    "previewImage": "test",
  },
  "Review": {
    "id": 1,
    "userId": 1,
    "productId": 1,
    "stars": 5,
    "headline": "test",
    "previewImage": "test",
    "body": "test",
  }
  "Question": {
    "id": 1,
    "userId": 1,
    "productId": 1,
    "body": "test",
  }
}
  ],
}

  • Error Response: Query parameter validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation Error",
  "statusCode": 400,
  "errors": {
    "page": "Page must be greater than or equal to 0",
    "size": "Size must be greater than or equal to 0",
    "minPrice": "Maximum price must be greater than or equal to 0",
    "maxPrice": "Minimum price must be greater than or equal to 0"
  }
}
Clone this wiki locally