Yesterday, I set up Flask-SQLAlchemy with models, migrations, and database operations. Today I put it all together, building a complete CRUD backend with both HTML views and API routes in the same Flask app. This is where everything from the past few days connects into something that actually works end-to-end.
Let's see it in action
To understand how the CRUD backend and API works in Flask, let's build a simple notes app where users can create, read, update, and delete notes. Each note has a title, content, and a created timestamp. The app exposes both:
- HTML routes — pages rendered with Jinja2 templates
- API routes — JSON responses for programmatic access
Same database, same models, two interfaces. Exactly like DevBoard served both HTML and a DRF API.
Project Structure
notes-app/
app.py
models.py
forms.py
templates/
base.html
notes/
list.html
detail.html
form.html
delete.html
static/
css/
style.css
.env
.gitignore
requirements.txt
Setup
# app.py
import os
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from dotenv import load_dotenv
load_dotenv()
app = Flask(__name__)
app.config['SECRET_KEY'] = os.environ.get('SECRET_KEY', 'dev-key')
app.config['SQLALCHEMY_DATABASE_URI'] = os.environ.get('DATABASE_URL', 'sqlite:///notes.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
db = SQLAlchemy(app)
migrate = Migrate(app, db)
The Model
# models.py
from datetime import datetime
from app import db
class Note(db.Model):
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200), nullable=False)
content = db.Column(db.Text, nullable=False)
is_pinned = db.Column(db.Boolean, default=False)
created_at = db.Column(db.DateTime, default=datetime.utcnow)
updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
def to_dict(self):
return {
'id': self.id,
'title': self.title,
'content': self.content,
'is_pinned': self.is_pinned,
'created_at': self.created_at.isoformat(),
'updated_at': self.updated_at.isoformat(),
}
def __repr__(self):
return f'<Note {self.title}>'
The to_dict() method is important: it serializes the model instance to a Python dictionary that can be passed to jsonify(). In Django, we had DRF serializers for this. In Flask, without DRF, you write this method manually. It's simple, but you need to remember to do it for every model you want to expose through an API.
The Form
# forms.py
from flask_wtf import FlaskForm
from wtforms import StringField, TextAreaField, BooleanField
from wtforms.validators import DataRequired, Length
class NoteForm(FlaskForm):
title = StringField('Title', validators=[
DataRequired(),
Length(min=1, max=200)
])
content = TextAreaField('Content', validators=[
DataRequired()
])
is_pinned = BooleanField('Pin this note')
HTML CRUD Routes
List — Read All
from flask import render_template, request
@app.route('/notes')
def note_list():
page = request.args.get('page', 1, type=int)
notes = Note.query.order_by(
Note.is_pinned.desc(),
Note.created_at.desc()
).paginate(page=page, per_page=10, error_out=False)
return render_template('notes/list.html', notes=notes)
Pinned notes appear first, then by newest. .paginate() handles splitting results across pages.
Detail — Read One
@app.route('/notes/<int:id>')
def note_detail(id):
note = Note.query.get_or_404(id)
return render_template('notes/detail.html', note=note)
get_or_404 means if someone requests a note ID that doesn't exist, Flask automatically returns a 404 response. No manual check needed.
Create
from flask import redirect, url_for, flash
from forms import NoteForm
@app.route('/notes/new', methods=['GET', 'POST'])
def note_create():
form = NoteForm()
if form.validate_on_submit():
note = Note(
title=form.title.data,
content=form.content.data,
is_pinned=form.is_pinned.data
)
db.session.add(note)
db.session.commit()
flash('Note created successfully.', 'success')
return redirect(url_for('note_detail', id=note.id))
return render_template('notes/form.html', form=form, title='New Note')
Update
@app.route('/notes/<int:id>/edit', methods=['GET', 'POST'])
def note_edit(id):
note = Note.query.get_or_404(id)
form = NoteForm(obj=note)
if form.validate_on_submit():
note.title = form.title.data
note.content = form.content.data
note.is_pinned = form.is_pinned.data
db.session.commit()
flash('Note updated.', 'success')
return redirect(url_for('note_detail', id=note.id))
return render_template('notes/form.html', form=form, title='Edit Note', note=note)
NoteForm(obj=note) pre-populates the form with the existing note data, equivalent to Django's form = NoteForm(instance=note).
Delete
@app.route('/notes/<int:id>/delete', methods=['GET', 'POST'])
def note_delete(id):
note = Note.query.get_or_404(id)
if request.method == 'POST':
db.session.delete(note)
db.session.commit()
flash('Note deleted.', 'success')
return redirect(url_for('note_list'))
return render_template('notes/delete.html', note=note)
API Routes
Now the same operations as JSON endpoints. Flask handles both HTML and API routes in the same app; no separate framework needed for simple cases.
API List — GET all notes
from flask import jsonify
@app.route('/api/notes', methods=['GET'])
def api_note_list():
page = request.args.get('page', 1, type=int)
per_page = request.args.get('per_page', 10, type=int)
pagination = Note.query.order_by(Note.created_at.desc()).paginate(
page=page,
per_page=per_page,
error_out=False
)
return jsonify({
'notes': [note.to_dict() for note in pagination.items],
'total': pagination.total,
'pages': pagination.pages,
'current_page': pagination.page,
'has_next': pagination.has_next,
'has_prev': pagination.has_prev,
})
API Detail — GET one note
@app.route('/api/notes/<int:id>', methods=['GET'])
def api_note_detail(id):
note = Note.query.get_or_404(id)
return jsonify(note.to_dict())
API Create — POST
@app.route('/api/notes', methods=['POST'])
def api_note_create():
data = request.get_json()
if not data:
return jsonify({'error': 'No data provided'}), 400
title = data.get('title', '').strip()
content = data.get('content', '').strip()
if not title:
return jsonify({'error': 'Title is required'}), 400
if not content:
return jsonify({'error': 'Content is required'}), 400
note = Note(
title=title,
content=content,
is_pinned=data.get('is_pinned', False)
)
db.session.add(note)
db.session.commit()
return jsonify(note.to_dict()), 201
API routes validate incoming JSON manually — there's no WTForms here since forms are for HTML. The validation pattern is straightforward: check required fields, return 400 with an error message if invalid, return 201 with the created object if successful.
API Update — PUT
@app.route('/api/notes/<int:id>', methods=['PUT'])
def api_note_update(id):
note = Note.query.get_or_404(id)
data = request.get_json()
if not data:
return jsonify({'error': 'No data provided'}), 400
if 'title' in data:
note.title = data['title'].strip()
if 'content' in data:
note.content = data['content'].strip()
if 'is_pinned' in data:
note.is_pinned = data['is_pinned']
db.session.commit()
return jsonify(note.to_dict())
Only update fields that are actually present in the request — this makes PUT behave more like PATCH. Good practice for API updates.
API Delete — DELETE
@app.route('/api/notes/<int:id>', methods=['DELETE'])
def api_note_delete(id):
note = Note.query.get_or_404(id)
db.session.delete(note)
db.session.commit()
return jsonify({'message': 'Note deleted successfully'}), 200
API Search
@app.route('/api/notes/search', methods=['GET'])
def api_note_search():
keyword = request.args.get('q', '').strip()
if not keyword:
return jsonify({'error': 'Search query required'}), 400
notes = Note.query.filter(
db.or_(
Note.title.ilike(f'%{keyword}%'),
Note.content.ilike(f'%{keyword}%')
)
).order_by(Note.created_at.desc()).all()
return jsonify({
'query': keyword,
'count': len(notes),
'notes': [note.to_dict() for note in notes]
})
ilike is case-insensitive LIKE, searches regardless of capitalization. db.or_ is SQLAlchemy's equivalent of Django's Q objects for OR conditions.
Error Handling for the API
When get_or_404 triggers a 404, Flask returns an HTML error page by default; not ideal for an API. Register JSON error handlers:
@app.errorhandler(404)
def not_found(e):
if request.path.startswith('/api/'):
return jsonify({'error': 'Resource not found'}), 404
return render_template('404.html'), 404
@app.errorhandler(400)
def bad_request(e):
if request.path.startswith('/api/'):
return jsonify({'error': 'Bad request'}), 400
return render_template('400.html'), 400
@app.errorhandler(500)
def server_error(e):
if request.path.startswith('/api/'):
return jsonify({'error': 'Internal server error'}), 500
return render_template('500.html'), 500
Check request.path.startswith('/api/') to decide whether to return JSON or HTML. API routes get JSON errors, HTML routes get rendered error pages. One error handler, two behaviors.
A Helper for API Responses
When your API grows, you end up repeating the same response structure everywhere. A small helper keeps things consistent:
def api_response(data=None, message=None, status=200, error=None):
response = {}
if data is not None:
response['data'] = data
if message:
response['message'] = message
if error:
response['error'] = error
return jsonify(response), status
# usage
return api_response(data=note.to_dict(), status=201)
return api_response(error='Title is required', status=400)
return api_response(message='Note deleted', status=200)
Consistent response shape across every endpoint. Clients consuming the API always know what to expect.
The Complete URL Map
HTML routes:
GET /notes — list all notes
GET /notes/<id> — note detail
GET /notes/new — create form
POST /notes/new — submit create form
GET /notes/<id>/edit — edit form
POST /notes/<id>/edit — submit edit form
GET /notes/<id>/delete — delete confirmation
POST /notes/<id>/delete — confirm delete
API routes:
GET /api/notes — list all notes (JSON)
POST /api/notes — create a note (JSON)
GET /api/notes/<id> — get one note (JSON)
PUT /api/notes/<id> — update a note (JSON)
DELETE /api/notes/<id> — delete a note (JSON)
GET /api/notes/search — search notes (JSON)
Two complete interfaces, one database, one Flask app. No DRF needed for this scale.
Flask API vs Django DRF
The difference is clear now having used both:
| Flask (manual) | Django DRF | |
|---|---|---|
| Serialization |
to_dict() method on model |
ModelSerializer class |
| Validation | Manual in view | Form or Serializer validators |
| CRUD boilerplate | Write each endpoint |
ModelViewSet in ~5 lines |
| URL registration |
@app.route per endpoint |
Router auto-generates |
| Auth | Manual check in each view | Permission classes |
Flask's approach is more code but more transparent; you see exactly what every endpoint does. DRF's approach is less code but more magic. For small APIs, Flask's manual approach is perfectly fine. For large APIs with many models, DRF's automation pays off significantly.
Wrapping Up
Today, the app became real: models, forms, HTML pages, and a JSON API all working together. The to_dict() pattern for serialization, get_or_404 for safe lookups, and the path-based error handler split between JSON and HTML are the three patterns worth remembering from today.
Thanks for reading. Feel free to share your thoughts!