lightapi 0.1.5__tar.gz → 0.1.7__tar.gz

lightapi-0.1.7/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: lightapi
+Version: 0.1.7
+Summary: A lightweight framework for building API endpoints using Python's native libraries.
+Project-URL: Repository, https://github.com/henriqueblobato/LightApi
+Project-URL: Issues, https://github.com/henriqueblobato/LightApi/issues
+Project-URL: Homepage, https://github.com/henriqueblobato/LightApi
+Author-email: iklobato <iklobato1@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,endpoint,framework,lightweight,rest,restful
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.8.1
+Requires-Dist: aiohttp<4.0.0,>=3.9.5
+Requires-Dist: pyjwt<3.0.0,>=2.8.0
+Requires-Dist: pyyaml>=5.1
+Requires-Dist: redis<6.0.0,>=5.0.0
+Requires-Dist: sqlalchemy<3.0.0,>=2.0.30
+Requires-Dist: starlette<1.0.0,>=0.37.0
+Requires-Dist: uvicorn<1.0.0,>=0.30.0
+Provides-Extra: dev
+Requires-Dist: black<24.0.0,>=23.3.0; extra == 'dev'
+Requires-Dist: flake8<7.0.0,>=6.0.0; extra == 'dev'
+Requires-Dist: isort<6.0.0,>=5.12.0; extra == 'dev'
+Requires-Dist: mypy<2.0.0,>=1.3.0; extra == 'dev'
+Requires-Dist: pytest<8.0.0,>=7.3.1; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-awesome-pages-plugin; extra == 'docs'
+Requires-Dist: mkdocs-git-authors-plugin; extra == 'docs'
+Requires-Dist: mkdocs-git-committers-plugin-2; extra == 'docs'
+Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == 'docs'
+Requires-Dist: mkdocs-glightbox; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: httpx<1.0.0,>=0.27.0; extra == 'test'
+Requires-Dist: pyjwt<3.0.0,>=2.8.0; extra == 'test'
+Requires-Dist: pytest<8.0.0,>=7.3.1; extra == 'test'
+Requires-Dist: redis<6.0.0,>=5.0.0; extra == 'test'
+Requires-Dist: starlette<1.0.0,>=0.37.0; extra == 'test'
+Requires-Dist: uvicorn<1.0.0,>=0.30.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# LightAPI: Instant Python REST APIs from SQL Databases
+
+[![PyPI version](https://badge.fury.io/py/lightapi.svg)](https://pypi.org/project/lightapi/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**LightAPI** is a modern Python framework for building high-performance REST APIs directly from your SQL database—no boilerplate, no manual endpoint wiring. Instantly expose CRUD endpoints from SQLAlchemy models or a YAML config, with full support for authentication, caching, validation, filtering, and OpenAPI documentation.
+
+---
+
+## Why use LightAPI?
+
+- **Zero-boilerplate Python REST API**: Instantly generate CRUD endpoints from your database schema.
+- **YAML-driven API generator**: Reflect your database and expose only the tables and operations you want.
+- **Async and Fast**: Built on aiohttp for high concurrency and low latency.
+- **Production-ready**: JWT authentication, Redis caching, request validation, and robust error handling.
+- **Automatic OpenAPI docs**: Swagger UI and OpenAPI JSON out of the box.
+- **Flexible**: Use with SQLite, PostgreSQL, MySQL, or any SQLAlchemy-supported database.
+- **Modern Python**: Type hints, async/await, and best practices throughout.
+
+---
+
+## Who is this for?
+
+- **Backend developers** who want to ship APIs fast, with minimal code.
+- **Data engineers** needing to expose existing databases as RESTful services.
+- **Prototypers** and **startups** who want to iterate quickly and scale later.
+- **Anyone** who wants a clean, maintainable, and extensible Python API stack.
+
+---
+
+## Features
+
+- 🚀 **Automatic CRUD endpoints** from SQLAlchemy models or YAML config
+- 🔄 **Database reflection**: Expose existing tables instantly
+- 🔐 **JWT authentication** with CORS support
+- ⚡ **Async performance** (aiohttp)
+- 💾 **Redis caching** with auto-invalidation
+- 🧪 **Request validation** and error handling
+- 🔍 **Filtering, pagination, and sorting**
+- 📖 **OpenAPI/Swagger documentation** auto-generated
+- 🔧 **Custom middleware** support
+- 🗄️ **Works with SQLite, PostgreSQL, MySQL, and more**
+- 📝 **Environment-based configuration**
+
+---
+
+## Quick Start
+
+### 1. Install LightAPI
+
+```bash
+pip install lightapi
+```
+
+### 2. Define your model (SQLAlchemy)
+
+```python
+from lightapi import LightApi
+from lightapi.database import Base
+from sqlalchemy import Column, Integer, String
+
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    name = Column(String(50))
+    email = Column(String(100))
+
+app = LightApi()
+app.register(User)
+
+if __name__ == "__main__":
+    app.run()
+```
+
+### 3. Or use YAML for instant API from your database
+
+```yaml
+# config.yaml
+database_url: sqlite:///mydata.db
+tables:
+  - name: users
+    crud: [get, post, put, patch, delete]
+  - name: orders
+    crud: [get, post]
+```
+
+```python
+from lightapi import LightApi
+api = LightApi.from_config('config.yaml')
+api.run(host="0.0.0.0", port=8081)
+```
+
+---
+
+## Example Endpoints (from YAML above)
+
+- `GET    /users/`         - List users
+- `POST   /users/`         - Create user
+- `GET    /users/{id}`     - Get user by ID
+- `PUT    /users/{id}`     - Replace user
+- `PATCH  /users/{id}`     - Update user
+- `DELETE /users/{id}`     - Delete user
+- `GET    /orders/`        - List orders
+- `POST   /orders/`        - Create order
+- `GET    /orders/{id}`    - Get order by ID
+
+---
+
+## Documentation
+
+- [Full Documentation](https://iklobato.github.io/lightapi/)
+- [Getting Started](https://iklobato.github.io/lightapi/getting-started/installation/)
+- [API Reference](https://iklobato.github.io/lightapi/api-reference/core/)
+- [Examples](https://iklobato.github.io/lightapi/examples/basic-rest/)
+
+---
+
+## FAQ
+
+**Q: Can I use LightAPI with my existing database?**  
+A: Yes! Use the YAML config to reflect your schema and instantly expose REST endpoints.
+
+**Q: What databases are supported?**  
+A: Any database supported by SQLAlchemy (PostgreSQL, MySQL, SQLite, etc.).
+
+**Q: How do I secure my API?**  
+A: Enable JWT authentication and CORS with a single line.
+
+**Q: Can I customize endpoints or add business logic?**  
+A: Yes, you can extend or override any handler, add middleware, and use validators.
+
+**Q: Is this production-ready?**  
+A: Yes. LightAPI is designed for both rapid prototyping and production deployment.
+
+---
+
+## Comparison
+
+| Feature                | LightAPI | FastAPI | Flask | Django REST |
+|------------------------|----------|--------|-------|-------------|
+| Zero-boilerplate CRUD  | ✅       | ❌     | ❌    | ❌          |
+| YAML-driven API        | ✅       | ❌     | ❌    | ❌          |
+| Async support          | ✅       | ✅     | ❌    | ❌          |
+| OpenAPI docs           | ✅       | ✅     | ❌    | ✅          |
+| Built-in Auth/Caching  | ✅       | ❌     | ❌    | ✅          |
+| DB Reflection          | ✅       | ❌     | ❌    | ❌          |
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+---
+
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409.  
+> To start your API, always use `api.run(host, port)`. Do not use external libraries or `app = api.app` to start the server directly.
+
+---
+
+**LightAPI** - *The fastest way to build Python REST APIs from your database.*

lightapi-0.1.7/README.md

@@ -0,0 +1,162 @@
+# LightAPI: Instant Python REST APIs from SQL Databases
+
+[![PyPI version](https://badge.fury.io/py/lightapi.svg)](https://pypi.org/project/lightapi/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**LightAPI** is a modern Python framework for building high-performance REST APIs directly from your SQL database—no boilerplate, no manual endpoint wiring. Instantly expose CRUD endpoints from SQLAlchemy models or a YAML config, with full support for authentication, caching, validation, filtering, and OpenAPI documentation.
+
+---
+
+## Why use LightAPI?
+
+- **Zero-boilerplate Python REST API**: Instantly generate CRUD endpoints from your database schema.
+- **YAML-driven API generator**: Reflect your database and expose only the tables and operations you want.
+- **Async and Fast**: Built on aiohttp for high concurrency and low latency.
+- **Production-ready**: JWT authentication, Redis caching, request validation, and robust error handling.
+- **Automatic OpenAPI docs**: Swagger UI and OpenAPI JSON out of the box.
+- **Flexible**: Use with SQLite, PostgreSQL, MySQL, or any SQLAlchemy-supported database.
+- **Modern Python**: Type hints, async/await, and best practices throughout.
+
+---
+
+## Who is this for?
+
+- **Backend developers** who want to ship APIs fast, with minimal code.
+- **Data engineers** needing to expose existing databases as RESTful services.
+- **Prototypers** and **startups** who want to iterate quickly and scale later.
+- **Anyone** who wants a clean, maintainable, and extensible Python API stack.
+
+---
+
+## Features
+
+- 🚀 **Automatic CRUD endpoints** from SQLAlchemy models or YAML config
+- 🔄 **Database reflection**: Expose existing tables instantly
+- 🔐 **JWT authentication** with CORS support
+- ⚡ **Async performance** (aiohttp)
+- 💾 **Redis caching** with auto-invalidation
+- 🧪 **Request validation** and error handling
+- 🔍 **Filtering, pagination, and sorting**
+- 📖 **OpenAPI/Swagger documentation** auto-generated
+- 🔧 **Custom middleware** support
+- 🗄️ **Works with SQLite, PostgreSQL, MySQL, and more**
+- 📝 **Environment-based configuration**
+
+---
+
+## Quick Start
+
+### 1. Install LightAPI
+
+```bash
+pip install lightapi
+```
+
+### 2. Define your model (SQLAlchemy)
+
+```python
+from lightapi import LightApi
+from lightapi.database import Base
+from sqlalchemy import Column, Integer, String
+
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    name = Column(String(50))
+    email = Column(String(100))
+
+app = LightApi()
+app.register(User)
+
+if __name__ == "__main__":
+    app.run()
+```
+
+### 3. Or use YAML for instant API from your database
+
+```yaml
+# config.yaml
+database_url: sqlite:///mydata.db
+tables:
+  - name: users
+    crud: [get, post, put, patch, delete]
+  - name: orders
+    crud: [get, post]
+```
+
+```python
+from lightapi import LightApi
+api = LightApi.from_config('config.yaml')
+api.run(host="0.0.0.0", port=8081)
+```
+
+---
+
+## Example Endpoints (from YAML above)
+
+- `GET    /users/`         - List users
+- `POST   /users/`         - Create user
+- `GET    /users/{id}`     - Get user by ID
+- `PUT    /users/{id}`     - Replace user
+- `PATCH  /users/{id}`     - Update user
+- `DELETE /users/{id}`     - Delete user
+- `GET    /orders/`        - List orders
+- `POST   /orders/`        - Create order
+- `GET    /orders/{id}`    - Get order by ID
+
+---
+
+## Documentation
+
+- [Full Documentation](https://iklobato.github.io/lightapi/)
+- [Getting Started](https://iklobato.github.io/lightapi/getting-started/installation/)
+- [API Reference](https://iklobato.github.io/lightapi/api-reference/core/)
+- [Examples](https://iklobato.github.io/lightapi/examples/basic-rest/)
+
+---
+
+## FAQ
+
+**Q: Can I use LightAPI with my existing database?**  
+A: Yes! Use the YAML config to reflect your schema and instantly expose REST endpoints.
+
+**Q: What databases are supported?**  
+A: Any database supported by SQLAlchemy (PostgreSQL, MySQL, SQLite, etc.).
+
+**Q: How do I secure my API?**  
+A: Enable JWT authentication and CORS with a single line.
+
+**Q: Can I customize endpoints or add business logic?**  
+A: Yes, you can extend or override any handler, add middleware, and use validators.
+
+**Q: Is this production-ready?**  
+A: Yes. LightAPI is designed for both rapid prototyping and production deployment.
+
+---
+
+## Comparison
+
+| Feature                | LightAPI | FastAPI | Flask | Django REST |
+|------------------------|----------|--------|-------|-------------|
+| Zero-boilerplate CRUD  | ✅       | ❌     | ❌    | ❌          |
+| YAML-driven API        | ✅       | ❌     | ❌    | ❌          |
+| Async support          | ✅       | ✅     | ❌    | ❌          |
+| OpenAPI docs           | ✅       | ✅     | ❌    | ✅          |
+| Built-in Auth/Caching  | ✅       | ❌     | ❌    | ✅          |
+| DB Reflection          | ✅       | ❌     | ❌    | ❌          |
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+---
+
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409.  
+> To start your API, always use `api.run(host, port)`. Do not use external libraries or `app = api.app` to start the server directly.
+
+---
+
+**LightAPI** - *The fastest way to build Python REST APIs from your database.*

{lightapi-0.1.5 → lightapi-0.1.7}/docs/advanced/authentication.md

@@ -732,3 +732,7 @@ app.add_middleware([SecurityHeadersMiddleware])
 ```
 
 This comprehensive authentication system provides enterprise-grade security while maintaining the simplicity and performance that LightAPI is known for. The modular design allows you to implement exactly the authentication strategy your application needs, from simple API keys to complex multi-factor authentication systems.
+
+> **Note:** All JWT-protected endpoints require the `LIGHTAPI_JWT_SECRET` environment variable to be set before running the server.
+
+> **Custom endpoints must specify their intended paths using `route_patterns`. See the mega example for a full-stack authentication and registration demo.**

{lightapi-0.1.5 → lightapi-0.1.7}/docs/api-reference/rest.md

@@ -753,4 +753,19 @@ class User(RestEndpoint):
 - All required fields must be defined as NOT NULL in your database schema for correct enforcement.
 - The API will return 409 Conflict if you attempt to create or update a record missing a NOT NULL field, or violating a UNIQUE or FOREIGN KEY constraint. 
 
-To start your API, always use `api.run(host, port)`. Do not use external libraries or 'app = api.app' to start the server directly. 
+To start your API, always use `api.run(host, port)`. Do not use external libraries or 'app = api.app' to start the server directly. 
+
+## Custom Endpoint Registration with route_patterns
+
+When registering custom (non-model) endpoints, you must specify the intended REST path(s) using the `route_patterns` attribute. Fallback to class names is not supported for custom endpoints.
+
+```python
+class HelloWorldEndpoint(RestEndpoint):
+    route_patterns = ["/hello"]
+    def get(self, request):
+        return {"message": "Hello, World!"}
+
+app.register(HelloWorldEndpoint)
+```
+
+> See the mega example for a comprehensive demonstration of registering multiple endpoints with custom paths. 

{lightapi-0.1.5 → lightapi-0.1.7}/docs/examples/auth.md

@@ -158,52 +158,41 @@ curl -X POST http://localhost:8000/auth/login \
 }
 ```
 
-### 2. Access Public Endpoint
+### 2. Access User Profile (JWT-protected)
 
-```bash
-curl http://localhost:8000/public
-```
-
-**Response:**
-```json
-{
-  "message": "This is public information"
-}
-```
-
-### 3. Access Protected Endpoint
+> **Note:** The `user_id` field in the profile must match the JWT `sub` claim (e.g., `user_1`).
 
 ```bash
-# Without token (will fail)
-curl http://localhost:8000/secret
-```
-
-**Response:**
-```json
-{
-  "error": "Authentication failed"
-}
-```
+curl -X POST http://localhost:8000/user_profiles \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{
+    "user_id": "user_1",
+    "full_name": "Admin User",
+    "email": "admin@example.com"
+  }'
 
-```bash
-# With valid token
 curl -H "Authorization: Bearer YOUR_TOKEN" \
-     http://localhost:8000/secret
+     http://localhost:8000/user_profiles
 ```
 
 **Response:**
 ```json
 {
-  "message": "Hello, admin! You have admin access.",
-  "secret_data": "This is protected information"
+  "id": 2,
+  "user_id": "user_1",
+  "full_name": "Admin User",
+  "email": "admin@example.com"
 }
 ```
 
-### 4. Access User Profile
+### 3. Troubleshooting
+
+- If you get `{ "error": "Profile not found" }`, ensure you created the profile with `user_id` matching the JWT `sub` claim.
+- Always set the environment variable before running the server:
 
 ```bash
-curl -H "Authorization: Bearer YOUR_TOKEN" \
-     http://localhost:8000/profile
+export LIGHTAPI_JWT_SECRET="your-super-secret-key"
 ```
 
 ## JWT Token Structure

{lightapi-0.1.5 → lightapi-0.1.7}/docs/index.md

@@ -160,3 +160,30 @@ LightAPI is released under the [MIT License](https://github.com/henriqueblobato/
 
 > To start your API, always use `api.run(host, port)`. Do not use external libraries or 'app = api.app' to start the server directly.
 
+## Mega Example: All Features in One App
+
+The `examples/mega_example.py` script demonstrates the full capabilities of LightAPI:
+- RESTful models (products, categories, orders, users, etc.)
+- Custom endpoints (auth, weather, hello, secret, public, etc.)
+- JWT authentication and protected resources
+- Middleware (logging, CORS, rate limiting, authentication)
+- Caching, filtering, pagination, and more
+
+**Available Endpoints:**
+
+| Path                  | Methods                                    | Description                  |
+|-----------------------|--------------------------------------------|------------------------------|
+| /products             | GET, POST, PUT, PATCH, DELETE, OPTIONS     | Product CRUD                 |
+| /categories           | GET, POST, PUT, PATCH, DELETE, OPTIONS     | Category CRUD                |
+| /orders               | GET, POST, PUT, PATCH, DELETE, OPTIONS     | Order CRUD                   |
+| /order_items          | GET, POST, PUT, PATCH, DELETE, OPTIONS     | Order item CRUD              |
+| /users                | GET, POST, PUT, PATCH, DELETE, OPTIONS     | User CRUD                    |
+| /user_profiles        | GET, POST, PUT, PATCH, DELETE, OPTIONS     | User profile (JWT protected) |
+| /auth/login           | POST, OPTIONS                              | JWT login                    |
+| /secret               | GET, OPTIONS (JWT required)                | Protected resource           |
+| /public               | GET, OPTIONS                               | Public resource              |
+| /weather/{city}       | GET, OPTIONS                               | Weather info (custom path)   |
+| /hello                | GET, OPTIONS                               | Hello world (custom path)    |
+
+> All endpoints are registered with explicit RESTful or custom paths using `route_patterns` or `__tablename__`.
+

{lightapi-0.1.5 → lightapi-0.1.7}/docs/tutorial/endpoints.md

@@ -33,6 +33,21 @@ app = LightApi()
 app.register({'/custom-users': CustomUserEndpoint})
 ```
 
+## Registering Custom Endpoints with route_patterns
+
+When defining a custom endpoint (not a SQLAlchemy model), always specify the intended path(s) using the `route_patterns` attribute:
+
+```python
+class HelloWorldEndpoint(RestEndpoint):
+    route_patterns = ["/hello"]
+    def get(self, request):
+        return {"message": "Hello, World!"}
+
+app.register(HelloWorldEndpoint)
+```
+
+> See the mega example for a comprehensive demonstration of this pattern.
+
 ## HTTP Method Configuration
 
 - `http_method_names`: List of allowed HTTP methods.

{lightapi-0.1.5 → lightapi-0.1.7}/examples/README.md

@@ -2,9 +2,9 @@
 
 This directory contains example applications demonstrating various features of the LightAPI framework.
 
-## Basic Examples
+## Example Features
 
-- **user_goal_example.py**: Comprehensive demonstration of intended LightAPI usage patterns
+- **comprehensive_ideal_usage.py**: Comprehensive demonstration of intended LightAPI usage patterns
   - Shows the exact API design philosophy and usage as envisioned
   - Demonstrates custom validators with field-specific validation methods
   - Implements JWT authentication with proper configuration
@@ -13,17 +13,17 @@ This directory contains example applications demonstrating various features of t
   - Includes CORS support and proper environment variable usage
   - **Note**: Some advanced features (caching + pagination) are commented out due to current limitations
 
-- **basic_rest_api.py**: A simple REST API with default CRUD operations
+- **rest_crud_basic.py**: A simple REST API with default CRUD operations
   - Demonstrates minimal setup for a REST endpoint
   - Shows automatic handling of GET, POST, PUT, DELETE operations
   - Illustrates SQLAlchemy model integration with LightAPI
 
-- **validation_example.py**: Data validation with custom validators
+- **validation_custom_fields.py**: Data validation with custom validators
   - Shows field-specific validation rules using Validator class
   - Demonstrates error handling for validation failures
   - Illustrates data transformation (price conversion between dollars and cents)
 
-- **auth_example.py**: JWT authentication with protected resources
+- **authentication_jwt.py**: JWT authentication with protected resources
   - Implements JWT token generation and verification
   - Shows protected endpoints requiring authentication
   - Demonstrates user information extraction from token
@@ -31,45 +31,31 @@ This directory contains example applications demonstrating various features of t
 
 ## Advanced Features
 
-- **custom_snippet.py**: Built-in middleware demonstration
+- **middleware_cors_auth.py**: Built-in middleware demonstration
   - Shows new `CORSMiddleware` and `AuthenticationMiddleware` classes
   - Demonstrates automatic CORS preflight handling with JWT authentication
   - Illustrates seamless integration of authentication with CORS support
   - Uses built-in middleware for cleaner, more maintainable code
 
-- **middleware_example.py**: Custom middleware implementation for request/response processing
-  - Demonstrates request/response lifecycle hooks
-  - Includes logging middleware with request timing
-  - Shows custom CORS headers management for cross-origin requests
-  - Implements rate limiting with custom window controls
-
-- **filtering_pagination_example.py**: Query filtering and result pagination
-  - Shows parameter-based filtering for REST endpoints
-  - Implements custom filter logic for search and range queries
-  - Demonstrates paginated results with metadata
-  - Illustrates dynamic sorting by different fields
-
-- **caching_example.py**: Response caching for improved performance
-  - Shows Redis cache implementation with automatic JSON serialization
-  - Demonstrates cache key generation strategies
-  - Includes time-to-live (TTL) management
-  - Shows manual cache invalidation (DELETE operations)
-  - Implements cache hit/miss HTTP headers
-  - Fixed JSON serialization issues for proper caching
-
-- **swagger_example.py**: Enhanced OpenAPI/Swagger documentation
-  - Demonstrates docstring-based API documentation
-  - Shows custom SwaggerGenerator implementation
-  - Illustrates request/response schema documentation
-  - Implements API grouping with tags
-  - Demonstrates security scheme definitions
-
-- **relationships_example.py**: Complex SQLAlchemy relationships (one-to-many, many-to-many)
-  - Shows many-to-many relationships with association tables
-  - Demonstrates one-to-many relationships with back references
-  - Illustrates cascade behaviors on related objects
-  - Shows nested data serialization across relationships
-  - Implements relationship handling in POST/PUT operations
+- **filtering_pagination.py**: Filtering and pagination
+  - Demonstrates filtering, pagination, and sorting of results
+  - Shows how to use query parameters for advanced queries
+
+- **middleware_custom.py**: Custom middleware and order
+  - Demonstrates how to add custom middleware
+  - Shows the order of middleware execution
+  - Includes logging, CORS, and rate limiting examples
+
+- **relationships_sqlalchemy.py**: SQLAlchemy relationships
+  - Demonstrates one-to-many and many-to-many relationships
+  - Shows how to query related resources
+
+- **swagger_openapi_docs.py**: Swagger/OpenAPI documentation
+  - Shows how to generate and customize API documentation
+  - Demonstrates validator docstrings for better docs
+
+- **general_usage.py**: General usage
+  - Shows custom validator, custom headers, and CRUD
 
 ## New Built-in Features (Latest Updates)
 
@@ -95,17 +81,17 @@ All examples now demonstrate improved CORS handling:
 Each example is self-contained and can be run directly:
 
 ```bash
-# Basic example
-python examples/basic_rest_api.py
+# Basic REST/CRUD example
+python examples/rest_crud_basic.py
 
-# Built-in middleware example (demonstrates new features)
-LIGHTAPI_JWT_SECRET="your-secret-key" python examples/custom_snippet.py
+# Built-in middleware, CORS, Auth example
+LIGHTAPI_JWT_SECRET="your-secret-key" python examples/middleware_cors_auth.py
 
-# Authentication with CORS
-LIGHTAPI_JWT_SECRET="your-secret-key" python examples/auth_example.py
+# JWT Authentication example
+LIGHTAPI_JWT_SECRET="your-secret-key" python examples/authentication_jwt.py
 
 # Caching with Redis (requires Redis running)
-python examples/caching_example.py
+python examples/caching_redis_custom.py
 ```
 
 Most examples will:
@@ -119,11 +105,11 @@ Most examples will:
 The examples now include improved CORS and authentication. Test with:
 
 ```bash
-# Start the custom_snippet example
-LIGHTAPI_JWT_SECRET="test-secret-key-123" python examples/custom_snippet.py
+# Start the middleware_cors_auth example
+LIGHTAPI_JWT_SECRET="test-secret-key-123" python examples/middleware_cors_auth.py
 
-# Start the user goal example (comprehensive demonstration)
-LIGHTAPI_JWT_SECRET="test-secret-key-123" python examples/user_goal_example.py
+# Start the comprehensive_ideal_usage example (comprehensive demonstration)
+LIGHTAPI_JWT_SECRET="test-secret-key-123" python examples/comprehensive_ideal_usage.py
 
 # Test CORS preflight (should work without authentication)
 curl -X OPTIONS http://localhost:8000/custom -v