Build Hello Model Server with Flask

Expected time: 20–30 minutes

Outcome: You can add a Flask blueprint, register its route, return a JSON response, and verify it with pytest.

This is a local practice exercise. It does not use Redis, a worker, a database, shared data, or an external provider. Keep this tutorial in the documentation, but remove the practice endpoint before your first pull request unless your reviewer explicitly asks you to retain it.

1. Confirm the Model Server Is Running

Follow either Run with Docker or Run Without Docker. Verify the existing Model Server root endpoint:

Invoke-RestMethod http://localhost:3531/

On macOS or Linux:

curl http://localhost:3531/

The response should report that the Model Server is running. If the request fails, fix the Model Server startup before adding a route.

2. Create a Blueprint

Create model-server/src/routes/hello.py:

from flask import Blueprint, jsonify


hello_bp = Blueprint("hello", __name__, url_prefix="/tutorial")


@hello_bp.get("/hello")
def hello():
    return jsonify(
        {
            "message": "Hello, Marsad!",
            "service": "model-server",
        }
    )

The blueprint keeps route behavior in src/routes/ instead of expanding the root app.py. Its URL prefix and route combine to produce /tutorial/hello.

The /tutorial prefix makes this exercise visibly separate from Marsad's production /api contracts. This temporary endpoint is not authenticated and must not be committed or adapted into a real API endpoint without applying the Model Server's authentication, validation, and integration rules.

3. Register the Blueprint

Open model-server/app.py and import the new blueprint with the other route imports:

from src.routes.hello import hello_bp

Register it with the other blueprints:

app.register_blueprint(hello_bp)

Restart the Model Server process so Flask imports the new module and registers its route. If you use Docker without a source-code bind mount, rebuild and restart the model-server service instead.

4. Call the Endpoint

In PowerShell:

Invoke-RestMethod http://localhost:3531/tutorial/hello

On macOS or Linux:

curl http://localhost:3531/tutorial/hello

The JSON response should contain:

{
  "message": "Hello, Marsad!",
  "service": "model-server"
}

Change the message to include your name, restart the API if necessary, and confirm that the response changes.

5. Add a Focused Route Test

Create model-server/tests/test_hello_route.py:

from flask import Flask

from src.routes.hello import hello_bp


def test_hello_returns_service_identity():
    app = Flask(__name__)
    app.register_blueprint(hello_bp)

    with app.test_client() as client:
        response = client.get("/tutorial/hello")

    assert response.status_code == 200
    assert response.get_json() == {
        "message": "Hello, Marsad!",
        "service": "model-server",
    }

This test creates a small Flask application containing only the blueprint under test. It does not need a live HTTP server, Redis, a worker, or a database.

If you changed the greeting to include your name, update the expected test value to match.

6. Run the Test

From model-server/, activate the same virtual environment used by the API and run:

pytest tests/test_hello_route.py

The result should report one passing test. Then inspect only the practice files and registration changes:

git status --short
git diff -- app.py src/routes/hello.py tests/test_hello_route.py

What You Just Learned

• A Flask Blueprint groups related endpoints outside app.py.
• url_prefix and the route path combine into the final URL.
• jsonify produces a JSON response with the correct content type.
• A blueprint has no effect until the application registers it.
• Flask's test client can exercise a route without starting the server.
• A focused pytest test should run without unrelated infrastructure.

Clean Up the Practice Endpoint

Keep the practice endpoint, its test, and its app.py registration if you are continuing to 3C. Integrate a Hello Image Job. The integration tutorial evolves this blueprint into an authenticated queued job.

If you are stopping after this exercise:

1. Remove model-server/src/routes/hello.py.
2. Remove model-server/tests/test_hello_route.py.
3. Remove the hello_bp import and app.register_blueprint(hello_bp) line from app.py.
4. Run git status --short and confirm that no Hello Model Server application file or registration change remains.

Do not remove src/routes/, tests/, or unrelated lines from app.py.

If the team decides to keep an equivalent endpoint, first define its real ownership and security requirements. Production Model Server routes must use the appropriate /api namespace, authentication, input validation, tests, and documentation.

Checkpoint

You are ready to continue when you can explain why the endpoint uses a blueprint, why registration is required, and why the focused test does not require a running Redis service.

Next: integrate a Hello image-generation job →