# Flask Structured API
A production-ready Flask API framework with built-in storage, authentication, and AI capabilities. Designed for developers who need a robust foundation for building scalable APIs while following best practices.
## ✨ Core Features
### 🏗️ Model-First Architecture
- SQLModel + Pydantic for type-safe database operations
- Comprehensive validation with detailed error messages
- Clear separation between core and custom components
- Standardized response formats
### 🔐 Authentication & Security
- JWT token-based authentication
- API key management with scoping
- Role-based access control (RBAC)
- Request validation and sanitization
- Hash-based secure storage
### 📦 Storage System
- On-demand request/response storage
- Session-based data organization
- Compression for large payloads
- TTL-based expiration
- Flexible querying with metadata filters
### 🤖 AI Integration
- Provider-agnostic interface
- Response validation
- Automatic retry mechanisms
- Error handling with fallbacks
### 🔧 Developer Experience
- OpenAPI/Swagger documentation
- Remote debugging support
- Environment-based configuration
- Comprehensive error handling
- Warning collection system
## 🚀 Getting Started
### Option 1: Using PyPI Package (Simplest)
```bash
# Install the core package
pip install flask-structured-api
# Create new project
mkdir my-api && cd my-api
# Initialize basic structure
flask-api init
# Install dependencies
pip install -r requirements.txt
```
Note: When using the PyPI package, you'll need to set up your own PostgreSQL and Redis services.
### Option 2: Clean Initialize with Docker (Recommended)
For a fresh start with full Docker support:
```bash
# Create and enter project directory
mkdir my-api && cd my-api
# Initialize empty git repo
git init
# Add boilerplate as remote
git remote add boilerplate https://github.com/julianfleck/flask-structured-api.git
# Pull files without history
git pull boilerplate main --allow-unrelated-histories
# Make initial commit
git add .
git commit -m "Initial commit from boilerplate"
# Start services
docker-compose up -d
```
### Option 3: Direct Clone
If you want to preserve boilerplate history (not recommended for production):
```bash
# Clone the repo
git clone https://github.com/julianfleck/flask-structured-api.git my-api
cd my-api
# Start services
docker-compose up -d
```
## ⚙️ Configuration
Essential environment variables:
```env
# Required
FLASK_APP=flask_structured_api.main:app
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=your-secret-key
# Optional
AI_PROVIDER=openai
AI_API_KEY=your-api-key
```
## 📚 Documentation
- [Getting Started Guide](docs/getting-started/README.md)
- [Architecture Overview](docs/architecture/README.md)
- [API Documentation](docs/api/README.md)
- [Development Guide](docs/development/README.md)
- [Deployment Guide](docs/deployment/README.md)
## 💡 Example Usage
### Protected Endpoint
```python
from flask import Blueprint
from flask_structured_api.core.auth import require_auth
from flask_structured_api.models.responses import SuccessResponse
bp = Blueprint('example', __name__)
@bp.route('/hello', methods=['GET'])
@require_auth
def hello_world():
return SuccessResponse(
message="Hello, World!",
data={"authenticated": True}
).dict()
```
### Storage Decorator
```python
from flask_structured_api.core.storage import store_api_data
@bp.route('/ai/generate', methods=['POST'])
@require_auth
@store_api_data() # Automatically stores request/response
def generate():
result = ai_service.generate(request.json)
return SuccessResponse(data=result).dict()
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Submit a pull request
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## 📝 License
This project is licensed under the Apache License 2.0 - see [LICENSE](LICENSE) and [NOTICE](NOTICE) for details.
When using this project, please include the following attribution in your documentation:
```
Based on Flask Structured API (https://github.com/julianfleck/flask-structured-api)
Created by Julian Fleck and contributors
```
Raw data
{
"_id": null,
"home_page": "https://github.com/julianfleck/flask-structured-api",
"name": "flask-structured-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "flask, api, boilerplate, ai, structured, sqlmodel, pydantic, orm, validation, postgresql, redis, celery, openapi, jwt, authentication, auth",
"author": "Julian Fleck",
"author_email": "Julian Fleck <dev@julianfleck.net>",
"download_url": "https://files.pythonhosted.org/packages/33/ca/357ca065ee138108970bbde1a8c0dc56a2d124a513bcbc567ae85e0f974b/flask_structured_api-0.1.3.tar.gz",
"platform": null,
"description": "# Flask Structured API\n\nA production-ready Flask API framework with built-in storage, authentication, and AI capabilities. Designed for developers who need a robust foundation for building scalable APIs while following best practices.\n\n## \u2728 Core Features\n\n### \ud83c\udfd7\ufe0f Model-First Architecture\n- SQLModel + Pydantic for type-safe database operations\n- Comprehensive validation with detailed error messages\n- Clear separation between core and custom components\n- Standardized response formats\n\n### \ud83d\udd10 Authentication & Security\n- JWT token-based authentication\n- API key management with scoping\n- Role-based access control (RBAC)\n- Request validation and sanitization\n- Hash-based secure storage\n\n### \ud83d\udce6 Storage System\n- On-demand request/response storage\n- Session-based data organization\n- Compression for large payloads\n- TTL-based expiration\n- Flexible querying with metadata filters\n\n### \ud83e\udd16 AI Integration\n- Provider-agnostic interface\n- Response validation\n- Automatic retry mechanisms\n- Error handling with fallbacks\n\n### \ud83d\udd27 Developer Experience\n- OpenAPI/Swagger documentation\n- Remote debugging support\n- Environment-based configuration\n- Comprehensive error handling\n- Warning collection system\n\n## \ud83d\ude80 Getting Started\n\n### Option 1: Using PyPI Package (Simplest)\n```bash\n# Install the core package\npip install flask-structured-api\n\n# Create new project\nmkdir my-api && cd my-api\n\n# Initialize basic structure\nflask-api init\n\n# Install dependencies\npip install -r requirements.txt\n```\n\nNote: When using the PyPI package, you'll need to set up your own PostgreSQL and Redis services.\n\n### Option 2: Clean Initialize with Docker (Recommended)\nFor a fresh start with full Docker support:\n\n```bash\n# Create and enter project directory\nmkdir my-api && cd my-api\n\n# Initialize empty git repo\ngit init\n\n# Add boilerplate as remote\ngit remote add boilerplate https://github.com/julianfleck/flask-structured-api.git\n\n# Pull files without history\ngit pull boilerplate main --allow-unrelated-histories\n\n# Make initial commit\ngit add .\ngit commit -m \"Initial commit from boilerplate\"\n\n# Start services\ndocker-compose up -d\n```\n\n### Option 3: Direct Clone\nIf you want to preserve boilerplate history (not recommended for production):\n\n```bash\n# Clone the repo\ngit clone https://github.com/julianfleck/flask-structured-api.git my-api\ncd my-api\n\n# Start services\ndocker-compose up -d\n```\n\n\n## \u2699\ufe0f Configuration\n\nEssential environment variables:\n```env\n# Required\nFLASK_APP=flask_structured_api.main:app\nDATABASE_URL=postgresql://user:password@localhost:5432/dbname\nREDIS_URL=redis://localhost:6379/0\nSECRET_KEY=your-secret-key\n\n# Optional\nAI_PROVIDER=openai\nAI_API_KEY=your-api-key\n```\n\n## \ud83d\udcda Documentation\n\n- [Getting Started Guide](docs/getting-started/README.md)\n- [Architecture Overview](docs/architecture/README.md)\n- [API Documentation](docs/api/README.md)\n- [Development Guide](docs/development/README.md)\n- [Deployment Guide](docs/deployment/README.md)\n\n## \ud83d\udca1 Example Usage\n\n### Protected Endpoint\n```python\nfrom flask import Blueprint\nfrom flask_structured_api.core.auth import require_auth\nfrom flask_structured_api.models.responses import SuccessResponse\n\nbp = Blueprint('example', __name__)\n\n@bp.route('/hello', methods=['GET'])\n@require_auth\ndef hello_world():\n return SuccessResponse(\n message=\"Hello, World!\",\n data={\"authenticated\": True}\n ).dict()\n```\n\n### Storage Decorator\n```python\nfrom flask_structured_api.core.storage import store_api_data\n\n@bp.route('/ai/generate', methods=['POST'])\n@require_auth\n@store_api_data() # Automatically stores request/response\ndef generate():\n result = ai_service.generate(request.json)\n return SuccessResponse(data=result).dict()\n```\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## \ud83d\udcdd License\n\nThis project is licensed under the Apache License 2.0 - see [LICENSE](LICENSE) and [NOTICE](NOTICE) for details.\n\nWhen using this project, please include the following attribution in your documentation:\n\n```\nBased on Flask Structured API (https://github.com/julianfleck/flask-structured-api)\nCreated by Julian Fleck and contributors\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A structured Flask API boilerplate with built-in AI capabilities, featuring SQLModel ORM and Pydantic validation",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://github.com/julianfleck/flask-structured-api#readme",
"Homepage": "https://github.com/julianfleck/flask-structured-api",
"Issues": "https://github.com/julianfleck/flask-structured-api/issues",
"Repository": "https://github.com/julianfleck/flask-structured-api.git"
},
"split_keywords": [
"flask",
" api",
" boilerplate",
" ai",
" structured",
" sqlmodel",
" pydantic",
" orm",
" validation",
" postgresql",
" redis",
" celery",
" openapi",
" jwt",
" authentication",
" auth"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bf0bfee8aceff6d0dcb95bbea4ebd1b1e8b5d4af1d1ccd8f4cd3c8f104384578",
"md5": "1cd620dbc17b5d49316c508cd9e81345",
"sha256": "0525528bf9c81528a9aca142eca421b1422c4dc7f5200aedab2e6c012b7f400a"
},
"downloads": -1,
"filename": "flask_structured_api-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1cd620dbc17b5d49316c508cd9e81345",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 81499,
"upload_time": "2024-11-23T02:03:10",
"upload_time_iso_8601": "2024-11-23T02:03:10.619459Z",
"url": "https://files.pythonhosted.org/packages/bf/0b/fee8aceff6d0dcb95bbea4ebd1b1e8b5d4af1d1ccd8f4cd3c8f104384578/flask_structured_api-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "33ca357ca065ee138108970bbde1a8c0dc56a2d124a513bcbc567ae85e0f974b",
"md5": "ca97b6fc9f4daf2295905189bbdaa250",
"sha256": "91aa4d66508a5aa9a7518a650d4c86c3810a3b5361e58f3a57e097194c50bd68"
},
"downloads": -1,
"filename": "flask_structured_api-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "ca97b6fc9f4daf2295905189bbdaa250",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 81343,
"upload_time": "2024-11-23T02:03:12",
"upload_time_iso_8601": "2024-11-23T02:03:12.687320Z",
"url": "https://files.pythonhosted.org/packages/33/ca/357ca065ee138108970bbde1a8c0dc56a2d124a513bcbc567ae85e0f974b/flask_structured_api-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 02:03:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "julianfleck",
"github_project": "flask-structured-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "flask-structured-api"
}
JSON
