# Flask

A Flask 3 API starter in Python 3.12 for developers who want a clean JSON API skeleton with no database. It uses an application factory and a blueprint, serves through Waitress locally and Gunicorn on Light Cloud, and comes with pytest tests and ruff linting.

- Framework: Flask (Python)
- Category: Starters / REST APIs
- Creates: a server app
- Plan: Free
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/starters/rest-apis/flask-api-starter
- Updated: 2026-11-21

## Features

- create_app() in app/__init__.py builds the app and registers the blueprint from app/routes.py
- GET / returns { "message": "Hello from Flask on Light Cloud" } through jsonify
- python main.py serves with Waitress on 0.0.0.0, reading PORT and defaulting to 8000
- Light Cloud runs gunicorn main:app, so the single-threaded development server never goes live
- pytest fixture in tests/conftest.py builds a fresh app per test and uses Flask's test client
- Tests cover the welcome route and a 404 on an unknown path
- ruff configured in pyproject.toml; Flask 3.0.3 and waitress 3.0.0 pinned in requirements.txt

## What you need

- Free plan: it runs as a server app, and the Free plan includes 3 server apps
- To run it locally: Python 3.12 and pip, in a virtual environment
- No API keys: it starts with nothing to configure

## About

main.py builds the app once with create_app() and exposes it as main:app, which is the object both Waitress and Gunicorn serve; the tests call the factory themselves so each one starts clean. Choosing Waitress for python main.py means local runs use the same kind of multi-threaded server as the deployed app. Unknown paths still get Flask's HTML 404 page, so a JSON error handler in create_app() is a sensible first change, followed by your own blueprints. On Light Cloud the deploy installs requirements.txt, adds Gunicorn at build time and runs gunicorn main:app on the platform's PORT, redeploying on every push to your copy.

## Questions

### How do I add a new route in Flask?

Add a function to the blueprint in app/routes.py, or create a new blueprint module in app/ and register it in create_app() with app.register_blueprint(things_bp).

### Why use Waitress or Gunicorn instead of flask run?

flask run starts Flask's development server, which is single-threaded and not meant for live traffic. This starter serves the same main:app object with Waitress locally and Gunicorn on Light Cloud.

### How do I make Flask return JSON for 404 errors?

Register an error handler in create_app(), for example app.register_error_handler(404, lambda e: ({"error": "Not found"}, 404)). Without it, Flask answers with its HTML error page.

### Is there a Flask API template with PostgreSQL?

This starter has no database. The flask-postgresql-crud-api template adds PostgreSQL and a full CRUD resource.

### Can I deploy this Flask app without Light Cloud?

Yes. Any host with Python 3.12 runs it with python main.py and PORT set, or with any WSGI server pointed at main:app.
