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

  1. Directory Tree
  2. Top-Level Files
  3. Models Directory
  4. Resources Directory
  5. Postman Collections

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 .

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 reqparse ensures valid inputs.
    • JWT protection (@jwt_required()) on sensitive endpoints.
    • Resource routing declared in app.py.

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.py ties everything together.
  • db.py centralizes database setup.
  • security.py handles 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.