The Adventures of Blink S2e3: Designing Hangman... and a Flask API

#!/bin/bash

COLLECTION_EXISTS=$(mongosh --username $MONGO_INITDB_ROOT_USERNAME --password $MONGO_INITDB_ROOT_PASSWORD --authenticationDatabase admin --quiet --eval "db.getSiblingDB('$DB_NAME').getCollectionNames().includes('$COLLECTION_NAME')")

if [ "$COLLECTION_EXISTS" = "false" ]
then
    echo "Collection $COLLECTION_NAME does not exist.  Initializing..."
    mongosh --username $MONGO_INITDB_ROOT_USERNAME --password $MONGO_INITDB_ROOT_PASSWORD --authenticationDatabase admin --eval "db.getSiblingDB('$DB_NAME').createCollection('$COLLECTION_NAME')"
    echo "Collection $COLLECTION_NAME created."
else
    echo "Collection $COLLECTION_NAME already exists."
fi

echo "Mongo initialization script ran" > /tmp/startup_complete.txt

FROM mongo:latest

ENV MONGO_INITDB_ROOT_USERNAME=${MONGO_INITDB_ROOT_USERNAME}
ENV MONGO_INITDB_ROOT_PASSWORD=${MONGO_INITDB_ROOT_PASSWORD}

COPY ./database/init_mongo.sh /docker-entrypoint-initdb.d/init_mongo.sh
RUN chmod -x /docker-entrypoint-initdb.d/init_mongo.sh

EXPOSE 27017

CMD ["mongod"]

  mongo:
    build:
      context: .
      dockerfile: ./database/Dockerfile
    container_name: mongo_container
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./database/mongo_data:/data/db
    ports:
      - "27017:27017"

# We have lots of dependencies, but there are two major frameworks 
# in play: flask (for API creation) and pymongo (for database 
# manipulation)
from flask import Flask, jsonify, request
from pymongo import MongoClient
from pymongo.errors import PyMongoError
from bson.objectid import ObjectId
from datetime import datetime
import os

# This defines the Flask object, which initializes the Flask framework
app = Flask(__name__)

# Here are the environment variables (we're storing them in .env with our other constants).  You need the URI, the database name, and the collection name (analogous to a "table" in other databases)
mongo_uri = os.getenv("MONGO_URI_API")
db_name = os.getenv("DB_NAME")
collection_name = os.getenv("COLLECTION_NAME")

# When testing locally, we bypass the .env and load the variables manually.  These are commented out to show you what the content of the variables would look like in .env.
# mongo_uri = "mongodb://blink:theadventuresofblink@localhost:27017/hangman?authSource=admin"
# db_name = "hangman"
# collection_name = "phrases"

# We need an object that allows us to communicate to the database.  Mongo makes this an easy initialization, just pass the URI.  Then we want variables to hold the database and collection info for easy access later.
client = MongoClient(mongo_uri)
db = client[db_name]
collection = db[collection_name]

# A "route" is a path that you add to the end of the URI when you want to access an API method.  If you're running your api on localhost port 5001 like I am, you'd access this method by the following:
# http://localhost:5001/add
# Of course, this is a POST, so you'd be required to create a proper HTTP POST request body with all the stuff - details later in the testing part!  After defining the route, you create the Python method just like any old Python program.
@app.route('/add', methods=['POST'])
def add_item():
    # POST requests come with parameters that we need.  Go get them.
    data = request.get_json()

    # Validate that 'phrase' is one of the parameters provided.
    if 'phrase' not in data:
        return jsonify({"error": "Missing required parameter 'phrase'"}), 400

    # Validate that 'hint' is one of the parameters provided.
    if 'hint' not in data:
        return jsonify({"error": "Missing required parameter 'hint'"}), 400

    # Build the JSON for the new item we're going to add to our collection.  Note that we're auto-creating a couple of parameters here too for our metrics purposes!
    new_item = {
        "phrase": data['phrase'],
        "hint": data['hint'],
        "last_used": None,  # Set to null initially since it hasn't been used yet
        "access_count": 0  # Start the counter at 0
    }

    # Put the new item in the mongo collection.  This is like "adding a row to a table" in a relational DB.
    collection.insert_one(new_item)
    # We need to respond to the POST so that the requester gets feedback on the success of our addition.  HTTP 201 == "Created"
    return jsonify({"status": "Item added", "id": str(new_item['_id'])}), 201


# This is our second route - on this one we're doing an HTTP GET so we don't **require** any parameters.  But we could have them if we needed them!  In this case, we're just asking for a random item from the collection so we don't need any.
@app.route('/random', methods=['GET'])
def get_random_item():
    try:
        # collection.aggregate gives you the ability to select a random item or list of items.  We just want one.
        random_item = list(collection.aggregate([{"$sample": {"size": 1}}]))

        # Did we get one, or was there an error?  If we got one, 
        # we're going to do a few things here:
        # 1 - Update the record's metrics to reflect that it's been
        #     chosen
        # 2 - Return the selected item to the requester
        if random_item:
            random_item = random_item[0]

            # Ensure _id is correctly handled as ObjectId
            record_id = random_item['_id']

            # Update the record with the current timestamp and increment the counter
            collection.update_one(
                {"_id": ObjectId(record_id)},
                {
                    "$set": {"last_used": datetime.now()},
                    "$inc": {"access_count": 1}
                }
            )

            # Return the updated document
            # This _id manipulation here is required because Mongo types the _id field in a collection as an Object rather than a string, and jsonify() won't handle it.  So we convert it here to a string to help it along.
            random_item['_id'] = str(random_item['_id'])
            random_item['last_used'] = datetime.now()
            random_item['access_count'] += 1
            # Here's your HTTP 200 OK that also returns the item.
            return jsonify(random_item), 200

        # This is the 'else' of the 'if random_item' above - if we get to this line we need to let them know we didn't find an item (it's most likely the collection is empty)
        return jsonify({"error": "No items found"}), 404
    # If we get an exception, we need to report it as a HTTP 500 so there's record that something went wrong.
    except PyMongoError as e:
        return jsonify({"error": str(e)}), 500

# This is your python "glue" for running a program
if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5001)

Flask==2.3.2
pymongo==4.5.0
python-dotenv==1.0.0

# Use an official Python runtime as a parent image.  I selected 3.12 because it's what I have installed locally, so to minimize the risk of compatibility issues, I matched it.
FROM python:3.12-slim

# We're going to put all of our code in /app inside the container.
WORKDIR /app

# Copy the current directory contents (our code) into the container at /app
COPY . /app

# Install the necessary dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Expose the port that Flask will run on
EXPOSE 5001

# Define environment variables for Flask
ENV FLASK_APP=api
ENV FLASK_ENV=development
ENV PYTHONPATH=/app

# Run Flask app when the container launches
CMD ["flask", "run", "--host=0.0.0.0", "--port=5001"]

  hangman-api:
    # This tells the application that it's going to build the container based on the contents of /db-api
    build:
      context: ./db-api
      dockerfile: Dockerfile
    # Our container will be named hangman-api
    container_name: hangman-api
    # Like the mongo, it will try to auto-restart if it fails
    restart: unless-stopped
    # We're sending the same .env file to both containers
    env_file:
      - .env
    # Port 5001 is where you'll be able to access the API.
    ports:
      - "5001:5001"
    # A VERY important line - this tells docker to only start this container AFTER mongo is running!
    depends_on:
      - mongo
    # This tells the container where to get its source code, and where on the container's file system the code will be stored
    volumes:
      - ./db-api:/app
    # The environment entry defines things that this container needs to access.  Adding the MONGO URI here allows this container to connect to that one as defined, so that the API can call the database.
    environment:
      - MONGO_URI=${MONGO_URI_API}

# Mac
docker compose up --build

# Windows / Linux
docker-compose up --build

ben@Anduril ~ % docker ps
CONTAINER ID   IMAGE                    COMMAND                  CREATED             STATUS             PORTS                      NAMES
e753dc7d8900   s2-hangman-hangman-api   "flask run --host=0.…"   About an hour ago   Up About an hour   0.0.0.0:5001->5001/tcp     hangman-api
acfc65b3f0e1   s2-hangman-mongo         "docker-entrypoint.s…"   About an hour ago   Up About an hour   0.0.0.0:27017->27017/tcp   mongo_container

curl -X POST http://localhost:5000/add \
-H "Content-Type: application/json" \
-d '{"phrase": "hello world", "hint": "programmer quote"}'

curl http://localhost:5001/random