rest-canvas 0.9.0

OpenAPI-driven decorator library for easy predictable and safe REST API implementation in python

REST Canvas

OpenAPI-driven decorator library for REST API endpoints in Django and Flask.

Overview

REST Canvas provides a decorator-based approach to building REST APIs that are automatically validated against OpenAPI specifications. It handles request validation, response formatting, pagination, sorting, filtering, and error handling based on your OpenAPI YAML files.

Features

• OpenAPI-driven: All validation and behavior driven by OpenAPI specifications
• Framework-agnostic: Works with Django, Flask, and standalone mode
• Automatic validation: Path parameters, query parameters, and request body validation at startup
• Request-centric design: All features accessible via unified Request object
• Feature declaration: Declare endpoint capabilities with simple markers (Fields, Sort, Filter)
• Pagination support: Both cursor-based and page-based pagination
• RCQL filtering: REST Canvas Query Language for powerful filtering (e.g., status==active&age>18)
• Sort support: Multi-field sorting with ascending/descending (e.g., name,-createdAt)
• Detail level selection: Control response verbosity with field groups (e.g., minimal, full)
• Type safety: Generic type hints for pagination: Request[PagePagination]
• Testing utilities: Built-in MockRequest for testing view functions in isolation

Installation

# Install from Git (once published)
pip install git+https://github.com/yourusername/rest-canvas.git

# Or install in editable mode for development
pip install -e .

# With development dependencies
pip install -e ".[dev]"

# With Django
pip install -e ".[django]"

# With Flask
pip install -e ".[flask]"

Configuration

REST Canvas is configured via the Config class, which allows you to customize behavior:

from rest_canvas import RestCanvas
from rest_canvas.core.config import Config
from rest_canvas.core.log import LoggerConfig, LogToConsole
from rest_canvas.core.log.logger_types import LogLevel

# Basic usage - starts with Standalone adapter
api = RestCanvas('openapi.yaml')

# Custom configuration
config = Config(
    debug=True,                          # Enable debug mode
    logger_config=LoggerConfig(
        min_log_level=LogLevel.INFO,    # Set logging level
        enabled=True,                    # Enable/disable logging
        processors=[LogToConsole()]      # Custom log processors
    )
)
api = RestCanvas('openapi.yaml', config=config)

Configuration Options

• debug: Enable debug mode for additional logging and validation (default: False)
• logger_config: LoggerConfig instance for customizing logging behavior

Framework Adapter Selection

REST Canvas always starts with the Standalone adapter. The adapter automatically switches when you register routes:

# Flask - adapter switches when you call register_flask_routes()
api = RestCanvas('openapi.yaml')
api.register_flask_routes(app)  # Now using FlaskAdapter

# Django - adapter switches when you call register_django_urls()
api = RestCanvas('openapi.yaml')
urlpatterns = api.register_django_urls()  # Now using DjangoAdapter

# Standalone - no registration needed (default)
api = RestCanvas('openapi.yaml')
# Call endpoints directly - stays with StandaloneAdapter

Note: You cannot switch adapters once routes are registered. Calling register_flask_routes() or register_django_urls() more than once will raise a RuntimeError.

Quick Start

Flask Example

from flask import Flask
from rest_canvas import RestCanvas, Request, PagePagination, Sort, Filter

app = Flask(__name__)

# Initialize REST API with OpenAPI spec
api = RestCanvas('openapi.yaml', mount_point='/api/v1')


# Declare features in decorator, access via request object
@api.endpoint('GET /users', Sort, Filter)
def list_users(request: Request[PagePagination]):
    """List users with pagination, sorting, and filtering."""
    users = User.query.all()

    # Filter with RCQL: ?filter=status==active&age>18
    if request.filter:
        users = apply_filter(users, request.filter)

    # Sort: ?sort=name,-createdAt (ascending name, descending createdAt)
    if request.sort:
        users = apply_sort(users, request.sort)

    # Pagination automatically populated from query params
    users_page = users[request.pagination.offset:request.pagination.limit]
    request.pagination.total = len(users)

    return [user.to_dict() for user in users_page]


# Auto-register all routes with Flask
api.register_flask_routes(app)

Django Example

from rest_canvas import RestCanvas, Request, CursorPagination, DetailLevel

# Initialize REST API
api = RestCanvas('openapi.yaml', mount_point='/api/v1')


@api.endpoint('GET /users/{userId}', DetailLevel)
def get_user_by_id(request: Request, user_id: int):
    """Get user by ID with detail level selection."""
    user = User.objects.get(id=user_id)

    # Return different fields based on request.detail_level
    # Query: ?detailLevel=minimal
    if request.detail_level == "minimal":
        return {"id": user.id, "name": user.name}
    else:
        return user.to_dict()


# In urls.py
urlpatterns = api.register_django_urls()

Key Features

• Request-centric design: All features (pagination, sort, filter, detail_level) accessible via request object
• Feature declaration: Declare features in decorator: @api.endpoint('GET /path', Sort, Filter, DetailLevel)
• Type-safe: Generic type hints for pagination: Request[PagePagination]
• Automatic parsing: Sort, filter, pagination, and detail level parameters parsed automatically
• OpenAPI validation: Function signatures and features validated against OpenAPI spec at startup
• RCQL filtering: Powerful query language with operators: ==, !=, <, <=, >, >=, =like=, ={val1,val2,...}
• Multi-field sorting: Sort by multiple fields with direction: ?sort=name,-createdAt
• Framework adapters: Seamless adaptation for Flask, Django, and standalone modes

Development Status

Current Version: 0.1.0 (Alpha)

This library is in active development. Recent refactoring has established a modular, request-centric architecture.

Completed Features

• ✅ OpenAPI-driven endpoint validation
• ✅ Request-centric design with unified Request object
• ✅ Framework adapters (Django, Flask, Standalone)
• ✅ Feature declaration system (Sort, Filter, DetailLevel)
• ✅ Pagination (Page-based and Cursor-based)
• ✅ RCQL filtering with comparison and logical operators
• ✅ Multi-field sorting with ascending/descending
• ✅ Detail level (field group) selection
• ✅ Automatic type coercion for query parameters
• ✅ CamelCase to snake_case conversion
• ✅ Testing utilities (MockRequest)

In Progress

• 🔄 Additional ORM appliers for filtering and sorting
• 🔄 Enhanced error messages and validation
• 🔄 Documentation improvements

Requirements

• Python >= 3.8
• PyYAML >= 6.0
• jsonschema >= 4.0

Development

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run tests with coverage
pytest --cov=rest_api_decorator --cov-report=html

# Format code
black .

# Lint code
flake8 rest_api_decorator tests

# Type check
mypy rest_api_decorator

Testing Your Views

The library provides MockRequest for testing your view functions in isolation:

from rest_canvas.testing import MockRequest

def test_list_users():
    # Create mock request with pagination, sort, and filter
    request = (MockRequest()
        .with_page_pagination(page=1, size=10)
        .with_sort('name,-createdAt')
        .with_filter('status==active'))

    # Call view function directly
    result = list_users(request)

    # Assert results
    assert len(result) <= 10
    assert request.pagination.total > 0

def test_get_user_by_id():
    # Create mock request for single resource with detail level
    request = MockRequest().with_detail_level('minimal')

    # Call view with path parameter
    result = get_user_by_id(request, user_id=42)

    # Assert minimal fields returned
    assert 'id' in result
    assert 'name' in result
    assert 'email' not in result  # Not included in minimal

Project Structure

rest_canvas/
├── public/                # Public API surface
│   ├── rest_canvas.py     # RestCanvas class (main entry point)
│   ├── features.py        # Feature markers (DetailLevel, Sort, Filter)
│   └── exceptions.py      # API exceptions
├── core/                  # Core implementation
│   ├── endpoint/          # Endpoint decorator and validation
│   ├── request/           # Request wrapper and validation
│   ├── open_api/          # OpenAPI spec loading and parsing
│   ├── pagination/        # Page and cursor pagination
│   ├── query/             # Query parameter parsing (sort, filter)
│   ├── view/              # View function introspection
│   ├── envelope/          # Response envelope formatting
│   └── serializer.py      # Datetime serialization
├── adapters/              # Framework adapters
│   ├── django_adapter.py
│   ├── flask_adapter.py
│   └── standalone_adapter.py
├── utils/                 # Utilities
└── testing/               # Testing utilities (MockRequest)

tests/
├── unit/                  # Unit tests
├── integration/           # Integration tests
└── fixtures/              # Test fixtures and OpenAPI specs

Key Concepts

RCQL (REST Canvas Query Language)

RCQL provides a powerful filtering syntax using URL-friendly operators:

# Comparison operators
?filter=status==active           # Equal
?filter=age>18                   # Greater than
?filter=age<=65                  # Less than or equal
?filter=name=like=%john%         # Pattern matching
?filter=color={red,blue}         # Set membership (IN)

# Logical operators (left-to-right evaluation)
?filter=status==active&age>18    # AND
?filter=role==admin|role==mod    # OR

# Complex expressions
?filter=status==active&age>18|premium==true
?filter=category={1,2,3}&status==active

Sort Syntax

Multi-field sorting with direction control:

?sort=name              # Ascending by name
?sort=-createdAt        # Descending by createdAt
?sort=name,-createdAt   # Multiple fields

Detail Levels

Control response verbosity with field groups defined in your OpenAPI spec:

?detailLevel=minimal    # Only essential fields
?detailLevel=full       # All fields including relations

The detailLevel enum in the OpenAPI spec must list levels from smallest to largest payload. When the parameter is not specified, the smallest (first-listed) level is returned by default.

Response Envelope

All responses share the {data, meta, message} envelope:

{
  "data": { "id": 123, "name": "John Doe" },
  "meta": {
    "timestamp": "2024-12-16T10:30:00Z",
    "requestId": "abc-123"
  },
  "message": ""
}

• data — the resource payload (empty object {} for error responses)
• meta — operational/technical metadata (timestamps, request tracking, pagination)
• message — user-facing communication at the envelope root; always present, empty string when there is nothing important to communicate. Error responses carry the error description here.

Architecture

REST Canvas uses a request-centric design where all query features flow through a unified Request object:

1. Decorator declaration: Features declared in @api.endpoint() decorator
2. Automatic parsing: Query parameters parsed and validated at request time
3. Request population: Parsed values populated in request.sort, request.filter, etc.
4. Type safety: Generic type hints for pagination: Request[PagePagination]
5. Framework agnostic: Same code works with Django, Flask, or standalone

This design ensures your view functions remain clean, testable, and framework-independent.

License

MIT License

Contributing

This is currently an internal project. Contribution guidelines will be added once the library reaches beta status.

Support

For issues and questions, please refer to the issue tracker (to be set up).