Skip to content

Latest commit

 

History

History
951 lines (608 loc) · 19.5 KB

REQUIREMENTS.md

File metadata and controls

951 lines (608 loc) · 19.5 KB
Raw

API Requirements

The Wood Creations company stakeholders want to create an online storefront to showcase their great product creations.

Users need to be able to browse an index of all products, see the specifics of a single product, and add products to an order that they can view in a cart page.

Administrators should also be able to manage users, categories and products of the store.

These are the notes that describe the endpoints of the API, the database schema and the data contracts the frontend and backend have agreed upon to meet the requirements of the application.

API Endpoints

There are 4 main routes in the RESTful API: users, categories, products and orders.

All the endpoints of the API are under the route /api.

The following list is an overview of the exposed endpoints. More details for each endpoint can be found at the end of this document, in the API Endpoints Details section.

Users

Categories

Products

Orders

⬆️ Back to top

Data Contracts

The following data contracts specify the expected structure of the data returned from the API endpoints.

Category


{
  id: number;
  name: string;
}

Product


{
  id: number;
  name: string;
  price: string;
  category_id: number;
  category?: string;
  description?: string | null;
}

Order


{
  id: number;
  customer_id: number;
  status: Active | Complete;
  created_at: Date | string;
  completed_at?: Date | string | null;
  comments?: string | null;
  total?: string | null;
  number_of_products?: string | null;
  items?: [
    {
      id: number;
      order_id: number;
      product_id: number;
      quantity: number;
      engraving?: string | null;
      name?: string;
      price?: string;
      category_id?: number;
      description?: string;
    },
    ...
  ];
}

User

{
  id: number;
  username: string;
  firstname: string;
  lastname: string;
  role: Admin | Customer;
  password?: string | null;
  recentOrders?: Order[];
  currentOrder?: Order;
}

⬆️ Back to top

Database Schema

The following diagram depicts the database schema that address the API endpoints and data contracts above:

database-schema

⬆️ Back to top

API Endpoints Details

Success and error responses are described for special cases. In the Request Headers: the required headers for each request can be found.

Endpoints with the header

  Authorization: Bearer <accessToken>

require token authentication to be acccessed.

Users

[POST] /users/authenticate

Authenticates a user and provides access.

  • Request Headers:

    Content-Type: application/json

  • Request Body:

    {
    "username": string,
    "password": string
}

  • Success Response:

    Status Code: 200 OK

    Content: { "accessToken": string }

  • Error Response:

    • Status Code: 400 Bad Request

      Content:

      {
    "error": "CREDENTIALS_REQUIRED" | "USERNAME_REQUIRED" | "USERNAME_TOO_SHORT" | "PASSWORD_REQUIRED" | "PASSWORD_TOO_SHORT"
}

    • Status Code: 401 Unauthorized

      Content: { "error": "WRONG_CREDENTIALS" }

⬆️ Back to top

[GET] /users

Provides a list of all users. Available only for authenticated users with the Admin role.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

⬆️ Back to top

[GET] /users/:id

Returns the requested user including the current order and the 5 most recent completed orders. Available only for authenticated users with the Admin role.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_USER_ID" }

    • Status Code: 403 Forbidden

      Content: { "error": "FORBIDDEN_FOR_CUSTOMER" }

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

⬆️ Back to top

[POST] /users

Creates a user. Creating a user with the Admin role is not allowed.

  • Request Headers:

    Content-Type: application/json

  • Request Body:

    {
    "firstname": string,
    "lastname": string,
    "username": string,
    "password": string
}

  • Error Response:

    • Status Code: 400 Bad Request Content:

      {
    "error": "DATA_REQUIRED" | "USERNAME_REQUIRED" | "USERNAME_TOO_SHORT" | "PASSWORD_REQUIRED" | "PASSWORD_TOO_SHORT" | "FIRSTNAME_REQUIRED" | "FIRSTNAME_TOO_SHORT" | "LASTNAME_REQUIRED" | "LASTNAME_TOO_SHORT"
}

⬆️ Back to top

[PATCH] /users

Updates the authorized user and returns the updated user.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Request Body:

    At least one of the following is required.

    {
  "firstname"?: string,
  "lastname"?: string,
  "username"?: string,
  "password"?: string
 }

  • Error Response:

    • Status Code: 400 Bad Request Content:

      {
    "error": "DATA_REQUIRED" | "USERNAME_REQUIRED" | "USERNAME_TOO_SHORT" | "PASSWORD_REQUIRED" | "PASSWORD_TOO_SHORT" | "FIRSTNAME_REQUIRED" | "FIRSTNAME_TOO_SHORT" | "LASTNAME_REQUIRED" | "LASTNAME_TOO_SHORT"
}

⬆️ Back to top

[DELETE] /users/:id

Deletes the user with the specified id if the user exists and the user does not have the Admin role. Available only for authenticated users with the Admin role.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Success Response:

    Status Code: 204 No Content

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_USER_ID" }

    • Status Code: 403 Forbidden

      Content: { "error": "FORBIDDEN_FOR_CUSTOMER" | "ADMIN_DELETION_FORBIDDEN" }

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

⬆️ Back to top

Categories

Categories can only be managed for authenticated users with the Admin role. When users with the Customer role try to access the endpoind they will get an error response:

Status Code: 403 Forbidden

Content: { "error": "FORBIDDEN_FOR_CUSTOMER" }

[GET] /categories

Provides a list with the categories of the products.

  • Request Headers: 
    Content-Type: application/json
Authorization: Bearer <accessToken>

⬆️ Back to top

[GET] /categories/:id

Returns the category with the specified id.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_CATEGORY_ID" }

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

⬆️ Back to top

[POST] /categories

Creates a new category.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Request Body:

    {
    "name": string
}

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "NAME_REQUIRED" | "NAME_TOO_SHORT" }

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

⬆️ Back to top

[PATCH] /categories/:id

Updates the category with the specified id.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Request Body:

    {
    "name": string
}

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_CATEGORY_ID" | "NAME_REQUIRED" | "NAME_TOO_SHORT" }

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

⬆️ Back to top

[DELETE] /categories/:id

Deletes the category with the specified id.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Success Response:

    Status Code: 204 No Content

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_CATEGORY_ID" }

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

⬆️ Back to top

Products

[GET] /products

Provides a list of all products.

  • Request Headers: 
    Content-Type: application/json

⬆️ Back to top

[GET] /products/top-five

Provides a list of the 5 most popular products (most commonly ordered).

  • Request Headers: 
    Content-Type: application/json

⬆️ Back to top

[GET] /products/:id

Returns the product with the specified id.

  • Request Headers:

    Content-Type: application/json

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_PRODUCT_ID"}

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

⬆️ Back to top

[GET] /products/category/:id

Provides a list of all products that belong in the specified category.

  • Request Headers:

    Content-Type: application/json

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_CATEGORY_ID"}

⬆️ Back to top

[POST] /products

Creates a new product. Available only for authenticated users with the Admin role.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Request Body:

    {
  "name": string,
  "price": string,
  "category_id": number,
  "description": string | null
}

  • Error Response:

    • Status Code: 400 Bad Request Content:

      {
    "error": "DATA_REQUIRED" | "NAME_REQUIRED" | "NAME_TOO_SHORT" | "PRICE_REQUIRED" | "PRICE_MUST_BE_POSITIVE" | "INVALID_NUMBER_CATEGORY_ID"
}

⬆️ Back to top

[PATCH] /products/:id

Updates the product with the specified id. Available only for authenticated users with the Admin role.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Request Body:

At least one of the following is required.


{
"name"?: string,
"price"?: string,
"category_id"?: number,
"description"?: string | null
}

  • Error Response:

    • Status Code: 400 Bad Request Content:

      {
    "error": "DATA_REQUIRED" | "NAME_REQUIRED" | "NAME_TOO_SHORT" | "PRICE_REQUIRED" | "PRICE_MUST_BE_POSITIVE" | "INVALID_NUMBER_CATEGORY_ID"
}

⬆️ Back to top

[DELETE] /products/:id

Deletes the product with the specified id. Available only for authenticated users with the Admin role.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Success Response:

    Status Code: 204 No Content

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_PRODUCT_ID" }

    • Status Code: 403 Forbidden

      Content: { "error": "FORBIDDEN_FOR_CUSTOMER" }

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

⬆️ Back to top

Orders

All the orders endpoints can be accessed by the authorized and are related to that user.

[GET] /orders

Provides a list of all orders of the user.

  • Request Headers: 
    Content-Type: application/json
Authorization: Bearer <accessToken>

⬆️ Back to top

[GET] /orders/current

Returns the current order of the user.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Error Response:

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

⬆️ Back to top

[GET] /orders/completed

Provides a list of all completed orders of the user.

  • Request Headers: 
    Content-Type: application/json
Authorization: Bearer <accessToken>

⬆️ Back to top

[POST] /orders

Creates a new order for the user. Users are allowed to have only one active order.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Request Body:

    {
   "item": {
      "product_id": number,
      "quantity": number,
      "engraving": string | null
  },
  "comments": string | null,
  "calledAt": number (timestamp)
}

  • Error Response:

    • Status Code: 400 Bad Request Content:

      {
    "error": "CALLEDAT_REQUIRED" | "INVALID_TIMESTAMP_CALLEDAT" | "ORDER_ITEM_REQUIRED" | "INVALID_NUMBER_PRODUCT_ID" | "QUANTITY_REQUIRED" | "QUANTITY_MUST_BE_POSITIVE"
}

    • Status Code: 403 Forbidden Content: { "error": "CURRENT_ORDER_EXISTS" }

⬆️ Back to top

[POST] /orders/item

Adds a new order item in the current active order of the user.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Request Body:

    {
    "product_id": number,
    "quantity": number,
    "engraving": string | null
}

  • Error Response:

    • Status Code: 400 Bad Request Content:

      {
    "error": "INVALID_NUMBER_PRODUCT_ID" | "QUANTITY_REQUIRED" | "QUANTITY_MUST_BE_POSITIVE"
}

  • Status Code: 404 Not Found

    Content: { "error": "CURRENT_ORDER_NOT_FOUND" }

⬆️ Back to top

[PATCH] /orders/item

Updates an order item in the current active order of the user.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Request Body:

    At least one of the following is required.

    {
    "quantity?": number,
    "engraving?": string | null
}

  • Error Response:

    • Status Code: 400 Bad Request Content:

      {
    "error": "DATA_REQUIRED" | "INVALID_NUMBER_PRODUCT_ID" | "QUANTITY_REQUIRED" | "QUANTITY_MUST_BE_POSITIVE"
}

  • Status Code: 404 Not Found

    Content: { "error": "CURRENT_ORDER_NOT_FOUND" }

⬆️ Back to top

[DELETE] /orders/item/:id

Deletes the order item with the specified id in the current active order of the user. If there are no more items in the current order then the current order is deleted.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Success Response:

    Status Code: 200 OK Content: The current order or null

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_ORDER_ITEM_ID" }

    • Status Code: 404 Not Found

      Content: { "error": "NOT_FOUND" }

  • Status Code: 404 Not Found

    Content: { "error": "CURRENT_ORDER_NOT_FOUND" }

⬆️ Back to top

[PATCH] /orders/current/complete

Completes the current active order of the user.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Request Body:

    At least one of the following is required.

    {
    "calledAt": number (timestamp),
    "comments": string | null
}

  • Error Response:

    • Status Code: 400 Bad Request Content: { "error": "CALLEDAT_REQUIRED" | "INVALID_TIMESTAMP_CALLEDAT" }

  • Status Code: 404 Not Found

    Content: { "error": "CURRENT_ORDER_NOT_FOUND" }

⬆️ Back to top

[DELETE] /orders/current/complete

Deletes the current active order of the user.

  • Request Headers:

    Content-Type: application/json
Authorization: Bearer <accessToken>

  • Success Response:

    Status Code: 204 No Content

  • Error Response:

    • Status Code: 400 Bad Request

      Content: { "error": "INVALID_CATEGORY_ID" }

    • Status Code: 404 Not Found

      Content: { "error": "CURRENT_ORDER_NOT_FOUND" }

⬆️ Back to top