708's Wiki

Dudes of 708's knowledge base for getting started and tools we use

Edit the wiki on GitHub 708innovations/wiki

Visit our homepage dudesof708.com

ChompChomp Server Documentation


Back to homepagesoftware development guides


This is currently a work-in-progress guide. Please feel free to contribute to it.

Table of Contents

Development

The server runs on localhost, port 5050 when run in development mode. This means you can navigate to http://localhost:5050 to see your server in action.

Getting Started

To install, you’ll need Python 3.7 or newer. If you can’t figure out how to install Python, maybe it’s time to reevalulate if you know what you’re doing. (Just kidding, Google it or message the Discord channel.)

For the purposes of this guide, Python will be referred to as python. You may have your bindings set to python3 or python3.7 if you’re using macOS or Linux, or py -3 or py -3.7 if you’re using Windows.

  1. Clone the ChompChomp-server with git. If you don’t know how, see this guide.
  2. Create a virtual environment:

    python -m venv venv
    
  3. Activate the virtual environment. On Windows, run:

    .\venv\Scripts\activate
    

    or on Linux or macOS, run:

    source venv/bin/activate
    
  4. Install required dependencies with pip. You may need to use pip3 depending on how you have Python installed.

    pip install -r requirements.txt
    

Routes

You can test your routes however you want, including by opening a custom build of the app pointing at your computer, but I reccommend Postman. It’s easy to use and easy to set up.

There are six routes

Check Item

GET /items/exists: Checks if an item exists in the database

Requirements:

Provide a barcode to the database and it will tell you if it exists.

Returns:

If the item exists: status code 200 OK and:

{
  "exists": true
}

If the item does not exist: status code 404 NOT FOUND and:

{
  "exists": false
}

Get Item

GET /items/get: Gets an item from the database

Requirements:

Provide a barcode to the database and it will respond with the corresponding object.

Returns:

On success, it returns status code 200 OK with the corresponding item, except the images is replaced with the number of images:

{
  "barcode": "00000000",
  ...
  "images": 3
}

On error, it returns status code 400 BAD REQUEST if no barcode was provided or 404 NOT FOUND if the barcode does not exist.

{
  "error": true
}

New Item

POST /items/new: Takes a new item as a JSON object.

Requirements:

The input schema is:

As an example, the input looks something like this:

{
  "date": "2021-04-12T02:48:56.813Z",
  "store": "7 West Los Angeles, CA",
  "name": "Cheese Wheel",
  "price": "1.99",
  "weight": "16",
  "barcode": "00000000"
}

Returns:

On success, it returns status code 200 OK with a success message:

{
  "success": true
}

On error, it returns 400 BAD REQUEST or 500 INTERNAL SERVER ERROR depending on the error, with a corresponding error message:

{
  "error": "Something happened!"
}

Edit Item

POST /item/edit: Edits an item

Requirements:

The input schema is:

As an example, here is something you can provide:

{
  "barcode": "00000000",
  "weight": "16"
}

Returns:

The server returns status code 200 OK with the new item (sans images) if successful, like so:

{
  "barcode": "00000000",
  ...
  "images": 3
}

If the input was invalid, the server returns 400 BAD REQUEST with the corresponding error message or 500 SERVER ERROR if the input was unexpected. If the barcode does not exist, the server returns 404 NOT FOUND instead.

Example:

{
  "error": "Something happened!"
}

Observe Item

POST /item/observe: Adds a price observation to an item

Requirements:

The input schema is:

All inputs are strings. Additional data is ignored.

Returns:

The new item is returned with 200 OK on success (sans images). Example:

{
  "barcode": "00000000",
  ...
  "images": 3
}

You may get a 500 INTERNAL SERVER ERROR if the server can’t interpret the data, or 400 BAD REQUEST if you pass bad data to the server, or a 404 NOT FOUND if the barcode doesn’t already exist in the server. The corresponding return data is a descriptive error of what went wrong, like:

{
  "error": "Something happened!"
}

Add Image

POST /item/images/add: Add an image to the database

This endpoint hasn’t been implemented yet.

Get Images

GET /item/images/get: Get images from the database

Requirements:

Provide the barcode to the database and it will return an array of images according to the spec as they are stored in the database.

Returns:

On success, it returns status code 200 OK with images. Example:

[
  {
    "type": "base64/png",
    "data": "data:image/png;base64,..."
  },
  {
    "type": "base64/jpeg",
    "data": "data:image/jpeg;base64,..."
  },
  {
    "type": "uri",
    "data": "https://i.imgur.com/2dn06CW.png"
  }
]

It may return 404 NOT FOUND if the barcode doesn’t exist and 400 BAD REQUEST if no barcode was provided. If there are no images, it returns an empty array.

Database Schema

Although there are different ways to store the data, i.e. a custom rolled database structure, document-like structure as with no-SQL databases, or tables as with SQL-like databases, it will be documented here as a document-like structure. This makes it easier to read.

Click here to read about descriptions or here to see an example.

Schema Descriptions

This is the schema of database objects stored on the server.

Some notes:

Schema:

Schema Example

This example follows the schema described above in schema descriptions.

{
  "barcode": "00000000",
  "barcode_type": "EAN8",
  "name": "Cheese Wheel",
  "price": 1.99,
  "unit": "EA",
  "weight": 16,
  "prices": [
    {
      "store": 100,
      "date": "2021/01/01",
      "price": 1.99
    }
  ],
  "images": [
    {
      "type": "base64/png",
      "data": "data:image/png;base64,..."
    },
    {
      "type": "base64/jpeg",
      "data": "data:image/jpeg;base64,..."
    },
    {
      "type": "uri",
      "data": "https://i.imgur.com/2dn06CW.png"
    }
  ]
}

Contributing

So you want to contribute code, that’s great! Here’s a brief overview of the project…

Project Structure

This section is WIP.