Project Structure – Directory Layout
Below is an overview of the directory layout for the magarrent/REST-API-PYTHON-demo project. This section explains the purpose of each file and folder, and how they fit into the overall architecture.
Index
Directory Tree
PYTHON/
├── app.py # Application entry point
├── db.py # SQLAlchemy instance
├── security.py # JWT authenticate/identity functions
├── models/ # ORM models
│ ├── book.py
│ ├── store.py
│ └── user.py
└── resources/ # REST resource definitions
├── book.py
├── store.py
└── user.py
postman-collections/ # Postman collection for API testing
Top-Level Files
| File | Purpose | Key Notes |
|---|---|---|
| app.py | Entry point for the Flask application. Configures the app, JWT, and routes. | • Initializes Flask, Api, and JWT• Registers resources |
| db.py | Creates and exports the global SQLAlchemy instance used across models. |
• db = SQLAlchemy() |
| security.py | Defines authentication and identity functions for Flask-JWT. | • authenticate() and identity() implementations |
app.py
from flask import Flask
from flask_restful import Api
from flask_jwt import JWT
from security import authenticate, identity
from resources.user import UserRegister
from resources.book import Book, BookList
from resources.store import Store, StoreList
app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///data.db'
app.config['PROPAGATE_EXCEPTIONS'] = True
app.secret_key = 'SapanCrackle'
api = Api(app)
@app.before_first_request
def create_tables():
db.create_all()
jwt = JWT(app, authenticate, identity) # /auth
# Resource routing
api.add_resource(Store, '/store/<string:name>')
api.add_resource(StoreList, '/stores')
api.add_resource(Book, '/book/<string:title>')
api.add_resource(BookList, '/books')
api.add_resource(UserRegister, '/register')
if __name__ == '__main__':
from db import db
db.init_app(app)
app.run(port=5000, debug=True)
- Purpose: Bootstraps the app, sets up database tables, JWT authentication endpoint (
/auth), and RESTful routes for stores, books, and user registration .
Models Directory
Contains the ORM models mapping Python classes to database tables using SQLAlchemy.
| File | Model | Table Name | Relations |
|---|---|---|---|
| book.py | BookModel |
books |
FK → stores.id, relationship to StoreModel |
| store.py | StoreModel |
stores |
One-to-many with BookModel |
| user.py | UserModel |
users |
— |
Sample: book.py
from db import db
class BookModel(db.Model):
__tablename__ = 'books'
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(80))
author = db.Column(db.String(80))
isbn = db.Column(db.String(40))
release_date = db.Column(db.String(10))
price = db.Column(db.Float(precision=2))
store_id = db.Column(db.Integer, db.ForeignKey('stores.id'))
store = db.relationship('StoreModel')
def json(self):
return {
'title': self.title,
'price': self.price,
'author': self.author,
'isbn': self.isbn,
'release_date': self.release_date
}
@classmethod
def find_by_title(cls, title):
return cls.query.filter_by(title=title).first()
def save_to_db(self):
db.session.add(self)
db.session.commit()
def delete_from_db(self):
db.session.delete(self)
db.session.commit()
- Responsibilities:
- CRUD operations via
save_to_db(),delete_from_db(). - Query helpers like
find_by_title(). - Serialization through
json()method .
- CRUD operations via
Resources Directory
Implements RESTful resource controllers using Flask-RESTful. Each file defines endpoints and request parsing.
| File | Resource(s) | Endpoints |
|---|---|---|
| user.py | UserRegister |
POST /register |
| book.py | Book, BookList |
GET/POST/PUT/DELETE /book/<title>GET /books |
| store.py | Store, StoreList |
GET/POST/DELETE /store/<name>GET /stores |
Sample: resources/book.py
from flask_restful import Resource, reqparse
from flask_jwt import jwt_required
from models.book import BookModel
class Book(Resource):
parser = reqparse.RequestParser()
parser.add_argument('price', type=float, required=True, help="This field cannot be left blank!")
parser.add_argument('store_id', type=int, required=True, help="Every item needs a store_id.")
parser.add_argument('author', type=str, required=True, help="Every item needs an author.")
parser.add_argument('isbn', type=str, required=True, help="Every item needs an ISBN.")
parser.add_argument('release_date', type=str)
@jwt_required()
def get(self, title):
book = BookModel.find_by_title(title)
if book:
return book.json()
return {'message': 'Book not found'}, 404
def post(self, title):
if BookModel.find_by_title(title):
return {'message': f"Book '{title}' already exists."}, 400
data = Book.parser.parse_args()
book = BookModel(title, **data)
try:
book.save_to_db()
except:
return {"message": "An error occurred inserting the book."}, 500
return book.json(), 201
def delete(self, title):
book = BookModel.find_by_title(title)
if book:
book.delete_from_db()
return {'message': 'Book deleted.'}
return {'message': 'Book not found.'}, 404
def put(self, title):
data = Book.parser.parse_args()
book = BookModel.find_by_title(title)
if book:
book.price = data['price']
else:
book = BookModel(title, **data)
book.save_to_db()
return book.json()
class BookList(Resource):
def get(self):
return {'books': [b.json() for b in BookModel.query.all()]}
- Key Patterns:
- Request parsing with
reqparseensures valid inputs. - JWT protection (
@jwt_required()) on sensitive endpoints. - Resource routing declared in
app.py.
- Request parsing with
Postman Collections
Located under postman-collections/, this folder contains a Postman collection (Python Rest API.postman_collection.json) that bundles all endpoints for easy testing.
- Usage: Import into Postman to run and automate API calls.
- Includes:
/auth,/register,/books,/book/<title>,/stores,/store/<name>with example requests and tests.
This directory layout enforces a clear separation of concerns:
app.pyties everything together.db.pycentralizes database setup.security.pyhandles authentication logic.models/defines data schemas and persistence methods.resources/maps HTTP requests to business logic.postman-collections/aids in testing.
Together, these components form a modular, maintainable RESTful API built with Flask, Flask-RESTful, Flask-JWT, and SQLAlchemy.