Flask is one of the most popular web frameworks in the Python ecosystem. Created by Armin Ronacher in 2010, it combines simplicity with flexibility, being the ideal choice for both beginners and experienced developers who need granular control over their applications.
In this complete tutorial, you'll learn how to build a professional REST API with Flask, from initial setup to production deployment. We'll cover everything you need to build robust and scalable APIs.
🚀 Why Choose Flask for Your API?
Before diving into code, it's important to understand why Flask has become the choice of millions of developers worldwide. Flask offers a gentle learning curve, allowing you to start creating functional applications in just a few hours of study.
The Flask "micro" philosophy means you add only the features you need, unlike frameworks like Django that come with everything integrated. This modular approach is perfect for REST APIs, where you have total control over every aspect of the application.
Additionally, Flask has an extremely active community and exemplary documentation. Resources like the Flask Mega-Tutorial by Miguel Grinberg are a must-read for any developer wanting to master this framework.
📦 Environment Setup and Installation
To start developing with Flask, you first need to set up an isolated virtual environment. This ensures that your project dependencies don't conflict with other Python installations on your system.
If you're not familiar with virtual environments, I recommend reading our guide on venv Python - Virtual Environment to understand this fundamental concept. Setting up a virtual environment is considered one of the best practices in professional Python development.
# Create virtual environment
python -m venv venv-flask
# Activate on Windows
venv-flask\Scripts\activate
# Activate on Linux/Mac
source venv-flask/bin/activate
# Install Flask and extensions
pip install flask flask-sqlalchemy flask-jwt-extended flask-corsFlask-SQLAlchemy makes database integration easier, while Flask-JWT-Extended implements JSON Web Token authentication. Flask-CORS allows your API to be accessed by frontend applications from different domains.
It's important to check the installed Flask version to ensure compatibility. Run python -c "import flask; print(flask.__version__)" to confirm the installation.
🏗️ REST API Project Structure
A good project structure is essential to keep code organized and scalable. For Flask APIs, modular architecture with blueprints is Highly Recommended by the community.
Let's create the following directory structure that will separate responsibilities and make code maintenance easier in the future:
my-flask-project/
├── app/
│ ├── __init__.py
│ ├── models.py
│ ├── routes/
│ │ ├── __init__.py
│ │ ├── auth.py
│ │ └── products.py
│ └── utils/
├── run.py
└── requirements.txtThis structure allows each module to be developed and tested independently. Models define the database structure, while routes group API endpoints by functionality.
💻 Creating Your First Route
Let's start with the simplest possible example: a route that returns a welcome message. Create the app/__init__.py file with the following code:
from flask import Flask, jsonify
def create_app():
app = Flask(__name__)
@app.route('/')
def home():
return jsonify({
'message': 'Welcome to Flask API!',
'status': 'online',
'version': '1.0.0'
})
@app.route('/health')
def health_check():
return jsonify({'status': 'healthy'})
return appAlso create the run.py file at the project root:
from app import create_app
app = create_app()
if __name__ == '__main__':
app.run(debug=True, port=5000)Run the project with python run.py and access http://localhost:5000 in your browser. You should see the JSON response with the welcome message. The debug=True parameter enables debug mode, which automatically restarts the server when you make code changes.
🗄️ Setting Up Database with SQLAlchemy
SQLAlchemy is Python's most popular ORM (Object-Relational Mapper). It allows you to interact with databases using Python objects, abstracting the complexity of SQL queries.
Let's set up a SQLite database for our API. SQLite is perfect for development and testing since it doesn't require installing any additional server:
# Updated app/__init__.py
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_jwt_extended import JWTManager
from flask_cors import CORS
db = SQLAlchemy()
jwt = JWTManager()
def create_app():
app = Flask(__name__)
# Configuration
app.config['SECRET_KEY'] = 'your-secret-key-here'
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///database.db'
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
# Initialize extensions
db.init_app(app)
jwt.init_app(app)
CORS(app)
# Register blueprints
from app.routes import auth_bp, products_bp
app.register_blueprint(auth_bp, url_prefix='/api/auth')
app.register_blueprint(products_bp, url_prefix='/api/products')
# Create tables
with app.app_context():
db.create_all()
return appDatabase configuration is one of the most important aspects of API development. SQLite is great to start with, but for production applications you can easily migrate to PostgreSQL or MySQL by just changing the connection URI.
For production deployments, consider using managed services like ElephantSQL or Railway that offer generous free plans and are easy to set up.
📊 Creating Data Models
Models define the structure of your database tables. Let's create models for users and products in our API:
# app/models.py
from app import db
from datetime import datetime
from werkzeug.security import generate_password_hash, check_password_hash
class User(db.Model):
__tablename__ = 'users'
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80), unique=True, nullable=False)
email = db.Column(db.String(120), unique=True, nullable=False)
password_hash = db.Column(db.String(256), nullable=False)
created_at = db.Column(db.DateTime, default=datetime.utcnow)
def set_password(self, password):
self.password_hash = generate_password_hash(password)
def check_password(self, password):
return check_password_hash(self.password_hash, password)
def to_dict(self):
return {
'id': self.id,
'username': self.username,
'email': self.email,
'created_at': self.created_at.isoformat()
}
class Product(db.Model):
__tablename__ = 'products'
id = db.Column(db.Integer, primary_key=True)
name = db.Column(db.String(100), nullable=False)
description = db.Column(db.Text)
price = db.Column(db.Float, nullable=False)
stock = db.Column(db.Integer, default=0)
created_at = db.Column(db.DateTime, default=datetime.utcnow)
def to_dict(self):
return {
'id': self.id,
'name': self.name,
'description': self.description,
'price': self.price,
'stock': self.stock,
'created_at': self.created_at.isoformat()
}Here we're using Werkzeug's security functions to hash passwords. This is fundamental for your application security - never store passwords in plain text! The to_dict() method makes converting objects to JSON easy.
🔐 Implementing JWT Authentication
JSON Web Tokens (JWT) are the modern standard for REST API authentication. They allow the server to verify the client's identity without maintaining active sessions.
Let's implement the authentication system with user registration and login:
# app/routes/auth.py
from flask import Blueprint, request, jsonify
from flask_jwt_extended import create_access_token, jwt_required, get_jwt_identity
from app import db
from app.models import User
auth_bp = Blueprint('auth', __name__)
@auth_bp.route('/register', methods=['POST'])
def register():
data = request.get_json()
if not data or not data.get('username') or not data.get('password'):
return jsonify({'error': 'Incomplete data'}), 400
if User.query.filter_by(username=data['username']).first():
return jsonify({'error': 'User already exists'}), 409
if User.query.filter_by(email=data['email']).first():
return jsonify({'error': 'Email already in use'}), 409
new_user = User(
username=data['username'],
email=data['email']
)
new_user.set_password(data['password'])
db.session.add(new_user)
db.session.commit()
return jsonify({'message': 'User created successfully'}), 201
@auth_bp.route('/login', methods=['POST'])
def login():
data = request.get_json()
user = User.query.filter_by(username=data.get('username')).first()
if not user or not user.check_password(data.get('password')):
return jsonify({'error': 'Invalid credentials'}), 401
access_token = create_access_token(identity=user.id)
return jsonify({
'access_token': access_token,
'user': user.to_dict()
}), 200
@auth_bp.route('/profile', methods=['GET'])
@jwt_required()
def profile():
current_user_id = get_jwt_identity()
user = User.query.get(current_user_id)
return jsonify(user.to_dict()), 200Route protection with @jwt_required() ensures only authenticated users can access specific endpoints. JWT is widely supported and recommended by security experts as the best option for modern APIs.
For more information on secure authentication, check the OWASP Authentication Cheat Sheet, which presents best practices for authentication systems security.
📝 Creating Product Routes (Full CRUD)
The CRUD pattern (Create, Read, Update, Delete) is the backbone of any API. Let's implement all operations for product management:
# app/routes/products.py
from flask import Blueprint, request, jsonify
from flask_jwt_extended import jwt_required, get_jwt_identity
from app import db
from app.models import Product
products_bp = Blueprint('products', __name__)
@products_bp.route('/', methods=['GET'])
def list_products():
products = Product.query.all()
return jsonify([p.to_dict() for p in products]), 200
@products_bp.route('/<int:product_id>', methods=['GET'])
def get_product(product_id):
product = Product.query.get_or_404(product_id)
return jsonify(product.to_dict()), 200
@products_bp.route('/', methods=['POST'])
@jwt_required()
def create_product():
data = request.get_json()
if not data.get('name') or not data.get('price'):
return jsonify({'error': 'Name and price are required'}), 400
product = Product(
name=data['name'],
description=data.get('description', ''),
price=data['price'],
stock=data.get('stock', 0)
)
db.session.add(product)
db.session.commit()
return jsonify(product.to_dict()), 201
@products_bp.route('/<int:product_id>', methods=['PUT'])
@jwt_required()
def update_product(product_id):
product = Product.query.get_or_404(product_id)
data = request.get_json()
product.name = data.get('name', product.name)
product.description = data.get('description', product.description)
product.price = data.get('price', product.price)
product.stock = data.get('stock', product.stock)
db.session.commit()
return jsonify(product.to_dict()), 200
@products_bp.route('/<int:product_id>', methods=['DELETE'])
@jwt_required()
def delete_product(product_id):
product = Product.query.get_or_404(product_id)
db.session.delete(product)
db.session.commit()
return jsonify({'message': 'Product deleted successfully'}), 200This code implements all CRUD operations with authentication protection. For create, update, and delete operations, the user needs to be logged in (valid JWT token).
Data validation is crucial for API security. Always validate received data before processing it. Libraries like Marshmallow are excellent for creating robust validation schemas.
🔍 Validation and Error Handling
A professional API should handle errors properly and return correct HTTP codes. Let's implement a global error handler:
# Add to app/__init__.py
@app.errorhandler(404)
def not_found(error):
return jsonify({'error': 'Resource not found'}), 404
@app.errorhandler(500)
def internal_error(error):
db.session.rollback()
return jsonify({'error': 'Internal server error'}), 500
@app.route('/api/products/search')
def search_products():
query = request.args.get('q', '')
page = request.args.get('page', 1, type=int)
per_page = request.args.get('per_page', 10, type=int)
products = Product.query.filter(
Product.name.ilike(f'%{query}%')
).paginate(page=page, per_page=per_page, error_out=False)
return jsonify({
'products': [p.to_dict() for p in products.items],
'total': products.total,
'page': page,
'total_pages': products.pages
}), 200Pagination is essential for APIs that return large amounts of data. Without it, you may face performance and timeout issues. SQLAlchemy already provides native support for pagination with the .paginate() method.
🚀 Deployment and Production
When your API is ready for production, you'll need a robust server. The most popular options for Flask deployment include:
- Render: Free platform with Python support and automatic deployment via GitHub
- Railway: Great for applications that need integrated databases
- Fly.io: Global deployment with edge computing for low latency
- Heroku: Classic option with generous free tier
To deploy on Render, for example, you'll need a requirements.txt file and a Procfile:
# requirements.txt
flask==3.0.0
flask-sqlalchemy==3.1.1
flask-jwt-extended==4.6.0
flask-cors==4.0.0
gunicorn==21.2.0# Procfile
web: gunicorn run:app --workers 4Gunicorn is a production-ready WSGI server that replaces Flask's development server. It manages multiple workers to handle several simultaneous requests.
For production settings, never use debug mode and always set environment variables for passwords and secret keys. Never commit credentials to GitHub!
📈 Best Practices and Next Steps
Now that you have a functional REST API with Flask, here are some improvements you can implement:
- Rate Limiting: Limit the number of requests per user to prevent abuse
- Logging: Implement structured logs to monitor your application
- Documentation: Use Swagger/OpenAPI to document your endpoints
- Testing: Write unit and integration tests
- Database Migrations: Use Flask-Migrate to manage database changes
To make requests to your API, you can use the Python Requests library, which is the standard for HTTP communication in Python. It allows you to test all your API endpoints programmatically.
Flask is incredibly versatile and can be used for much more than REST APIs. You can build complete web applications, data dashboards, chatbots, and even machine learning APIs. The Python community offers thousands of extensions that expand the framework's capabilities.
Keep practicing and exploring Flask's official documentation. With dedication, you'll be able to create robust and professional web applications in no time!