JSON Specifications.txt

// NOTE: we agreed to use snake case :p


// ** categories vs subcategories issue **
// let's deal with "category" as an abstract concept
// a category is a collection of subcategories
// every product should have a property subcategory: List<subcategory>
//               but not a category property
// clicking on subcategory => redirects you to searching with no restriction filtered with the subcategory
// the only place where we would need category:
//      category page to display the subcategories
 
productSummary
    {
        "id": ..., 
        "name": ...,
        "price": number,
        "image": ImageURL,
        "discount": float
    },

product
    {
        "id": ..., 
        "name": ...,
        "price": {
            "$numberDouble": number
        },
        "image_list": List<ImageURL>,
        "subcategory": List<category>,
        "description": a paragraph,

        //! backend side edit required here
        // rest of properties should be inside the following object
        // to put them all in a table
        others: {
            "unit": ...,
            "..." : ...
        }
        "stock": {
             "$numberDouble": "0.0"
        },
        "discount": {
             "$numberDouble": "0.0"
         }
    },

category
    {
        "category": ...,
        "subcategory": [
            "subcat1",
            "subcat2",
            "subcat3",
        ]
    }

GET $URL/home:
    {
        slides: List<ImageURL>,
        content: [
            {
                title: sectionTitle,
                content: List<productSummary>
            },
            ...
        ]
    }

GET $URL/cat:
    [
        {
            title: sectionTitle,
            content: [
                {
                    title: sectionTitle,
                    image: subsectionImageURL
                }
            ]
        }
    ]

GET $URL/product/ID:
    product

GET $URL/search/keyword: Attach admin JWT token to return additional info of stock and subcategories
    body
    {
        "sort": "price+"(Ascending) | "price-"(Descending) | "relevance",
        // Optional arguments below
        "price_min": Int,
        "price_max": Int,
        "subcategories": [
            "subcat1",
            "subcat2",
            "subcat3"
        ]
    }
    
    return:
        List<productSummary>

POST $URL/auth/signup: Returns the id of user in db
    {
        "email": "grocery-on-rails@gmail.com",
        "password": "grocery-on-rails",
        // optional arguments below
        "username": "cswpy",
        "privilege": true // Default false, do not specify it for normal users
    }

POST $URL/auth/login: Returns the JWT token for access, save it for future requests, the token identifies an unique user, use it whenever user information is involved
    It also returns username and addresses for all users
    {
        "email": ...,
        "password": ...
    }

APIs for Admin, send below requests with a bearer token that belongs to a admin user with privilege

POST $URL/home: Create new product
    Follow product specification exactly
    Name, Price, Description are required

DELETE $URL/home: Delete a product
    {
        "id": ...
    }

POST $URL/product/<id>: Modify an existing product: it cannot add new keys that is not in the database
    {
        "key": "value",
    }

DELETE $URL/cat: Delete a category
    {
        "category": ...
    }

POST $URL/cat/<categoryname>: Add multiple subcats to the category
    {
        "subcategory": [
            "subcat1",
            "subcat2",
            ...
        ]
    }

DELETE $URL/cat/<categoryname>: Delete one subcat from the category
    {
        "name": subcat1
    }

GET $URL/admin/orders: get all orders from all users

POST $URL/admin/orders: modify an order
    body
    {
        "order_id": "...",
        // Optional arguments below
        "status": "delivered"/"pending"/"...",
        "delivery_time": double
    }

APIs for user, attach user login JWT token when sending requests

POST $URL/cart: Add new product to cart / Modify quantity of an existing product / Delete a product in cart, quantity should not be delta(increment/decrement), it should be the final quantity. Set quantity to 0 to delete it.
    {
        'product_id': ...,
        'quantity': 10
    }

GET $URL/cart: Get product summary and quantity
    {
        "product_summary": {
            ...
        },
        "quantity": 2
    }

POST $URL/userprofile: Update user profile settings, it will only change the first key-value pair. When updating address, whatever in the value will replace the original list
    {
        "email": ... OR
        "password": ... OR
        "address": [
            "1",
            "2",
            "3"
        ] OR
        "username": ...
    }

POST $URL/order: Clear the current cart and create an order based on it
    {
        "address": ...,
        "payment_method": ... (Not used in backend for now)
    }

Authorization Token:
In *headers* section of the request, include a key of "Authorization", and a value of "Bearer <token>"

GET $URL/admin/empty: Get product summary of out-of-stock items, ADMIN TOKEN REQUIRED
    {
        product_summary1,
        ...
    }

[!1]. not the full functionalities for now only search by keyword (not filter, or sort)
[!2]. no need to implement the show subcategory, as it can be displayed using the search