Flask API Starter for Python

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.

by Light CloudREST APIs

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

Tech stack

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.

FAQ

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.

Price
Free
Framework
Flask · Python
Plan
Free
Updated

Related templates

All rest api starters