tessl/pypi-flask-restx
Fully featured framework for fast, easy and documented API development with Flask
—
Pending
core-api.mddocs/
Core API Framework
The core API framework provides the fundamental classes and decorators for building REST APIs with Flask-RESTX. This includes the main Api class for managing the overall API, Resource class for individual endpoints, and Namespace system for organizing related functionality.
Capabilities
Api Class
The main entry point for creating REST APIs. Manages namespaces, global configuration, documentation generation, and request/response handling.
class Api:
def __init__(
self,
app=None,
version="1.0",
title=None,
description=None,
terms_url=None,
license=None,
license_url=None,
contact=None,
contact_url=None,
contact_email=None,
authorizations=None,
security=None,
doc="/",
default_id=None,
default="default",
default_label="Default namespace",
validate=None,
tags=None,
prefix="",
ordered=False,
default_mediatype="application/json",
decorators=None,
catch_all_404s=False,
serve_challenge_on_401=False,
format_checker=None,
url_scheme=None,
default_swagger_filename="swagger.json",
**kwargs
):
"""
Initialize the API.
Parameters:
- app: Flask application or Blueprint
- version: API version for documentation (default: "1.0")
- title: API title for documentation
- description: API description for documentation
- terms_url: Terms of service URL
- license: License name
- license_url: License URL
- contact: Contact name
- contact_url: Contact URL
- contact_email: Contact email address
- authorizations: Swagger authorization definitions
- security: Default security requirements
- doc: Documentation path (default: "/")
- default_id: Default ID generator function
- default: Default namespace name (default: "default")
- default_label: Default namespace label
- validate: Enable input payload validation
- tags: List of API tags for documentation
- prefix: URL prefix for all routes
- ordered: Preserve order in models and marshalling
- default_mediatype: Default response media type
- decorators: List of decorators to apply to all resources
- catch_all_404s: Handle 404 errors with error handler
- serve_challenge_on_401: Serve basic auth challenge on 401
- format_checker: JSON schema format checker
- url_scheme: URL scheme override
- default_swagger_filename: Default Swagger spec filename
- kwargs: Additional arguments
"""
def init_app(self, app, **kwargs):
"""Initialize with Flask app (factory pattern)."""
def namespace(self, name, description=None, path=None, **kwargs):
"""Create and register a namespace."""
def add_namespace(self, ns, path=None):
"""Add an existing namespace to the API."""
def route(self, *urls, **kwargs):
"""Decorator to register resources directly on the API."""
def marshal_with(self, fields, **kwargs):
"""Decorator for automatic response marshalling."""
def expect(self, *inputs, **kwargs):
"""Decorator for input validation."""
def doc(self, shortcut=None, **kwargs):
"""Decorator to add documentation to endpoints."""
def hide(self, func):
"""Hide endpoint from documentation."""
def deprecated(self, func):
"""Mark endpoint as deprecated."""
def param(self, name, description=None, _in='query', **kwargs):
"""Document a parameter."""
def response(self, code=200, description='Success', model=None, **kwargs):
"""Document a response."""
def header(self, name, description=None, **kwargs):
"""Document a header."""
def produces(self, mimetypes):
"""Specify response media types."""
def errorhandler(self, exception):
"""Register an error handler."""
def representation(self, mediatype):
"""Register a response representation."""
def as_postman(self, urlvars=False, swagger=False):
"""Export API as Postman collection."""
def url_for(self, resource, **values):
"""Generate URL for a resource."""
def documentation(self, func):
"""Decorator for custom documentation view."""
def make_response(self, data, *args, **kwargs):
"""Create Flask response."""
def owns_endpoint(self, endpoint):
"""Check if endpoint belongs to this API."""
def handle_error(self, e):
"""Handle exceptions."""
def default_endpoint(self, resource, namespace):
"""Generate default endpoint name."""
def model(self, name=None, model=None, mask=None, strict=False, **kwargs):
"""Create and register a model."""
def schema_model(self, name=None, schema=None):
"""Create and register a schema model."""
def clone(self, name, *specs):
"""Clone model with additional fields."""
def inherit(self, name, *specs):
"""Create inherited model."""
def parser(self):
"""Create request parser."""
@property
def specs_url(self):
"""URL for API specification."""
@property
def base_url(self):
"""Base URL for API."""
@property
def base_path(self):
"""Base path for API."""
@property
def payload(self):
"""Current request payload."""
@property
def refresolver(self):
"""JSON schema resolver."""
@property
def __schema__(self):
"""Swagger schema."""Resource Class
Base class for API resources/endpoints. Extends Flask's MethodView to provide REST API functionality with automatic documentation and validation.
class Resource:
def __init__(self, api=None, *args, **kwargs):
"""
Initialize the resource.
Parameters:
- api: Reference to the API instance
- args, kwargs: Additional arguments passed to MethodView
"""
def dispatch_request(self, *args, **kwargs):
"""Handle HTTP method dispatching with validation."""
def validate_payload(self, func):
"""Validate request payload against expected model."""
# Class attributes
representations = None # Custom representations
method_decorators = [] # Method decorators
# HTTP method handlers (implement as needed)
def get(self, *args, **kwargs):
"""Handle GET requests."""
def post(self, *args, **kwargs):
"""Handle POST requests."""
def put(self, *args, **kwargs):
"""Handle PUT requests."""
def patch(self, *args, **kwargs):
"""Handle PATCH requests."""
def delete(self, *args, **kwargs):
"""Handle DELETE requests."""
def head(self, *args, **kwargs):
"""Handle HEAD requests."""
def options(self, *args, **kwargs):
"""Handle OPTIONS requests."""Namespace Class
Groups related resources together with shared path prefix, decorators, and documentation. Similar to Flask Blueprints but specifically designed for REST APIs.
class Namespace:
def __init__(
self,
name,
description=None,
path=None,
decorators=None,
validate=None,
authorizations=None,
ordered=False,
**kwargs
):
"""
Initialize the namespace.
Parameters:
- name: Namespace name
- description: Optional description
- path: URL path prefix (defaults to '/name')
- decorators: List of decorators for all resources
- validate: Enable validation for this namespace
- authorizations: Authorization definitions
- ordered: Preserve field order in models
- kwargs: Additional arguments including 'api' reference
"""
def add_resource(self, resource, *urls, **kwargs):
"""
Register a resource with URL routes.
Parameters:
- resource: Resource class to register
- urls: One or more URL routes
- kwargs: Additional Flask routing arguments
"""
def route(self, *urls, **kwargs):
"""Decorator to route resources."""
def doc(self, shortcut=None, **kwargs):
"""Decorator to add documentation."""
def hide(self, func):
"""Hide endpoint from documentation."""
def abort(self, *args, **kwargs):
"""Abort with namespace context."""
def marshal_with(self, fields, **kwargs):
"""Decorator for response marshalling."""
def marshal_list_with(self, fields, **kwargs):
"""Decorator for marshalling list responses."""
def marshal(self, *args, **kwargs):
"""Marshal data with fields."""
def expect(self, *inputs, **kwargs):
"""Decorator for input validation."""
def param(self, name, description=None, _in='query', **kwargs):
"""Document a parameter."""
def response(self, code=200, description='Success', model=None, **kwargs):
"""Document a response."""
def header(self, name, description=None, **kwargs):
"""Document a header."""
def produces(self, mimetypes):
"""Specify response media types."""
def deprecated(self, func):
"""Mark endpoint as deprecated."""
def vendor(self, *args, **kwargs):
"""Add vendor extensions."""
def errorhandler(self, exception):
"""Register error handler for this namespace."""
def as_list(self, field):
"""Wrap field as list for marshalling."""
def add_model(self, name, definition):
"""Register model with this namespace."""
def model(self, name=None, model=None, mask=None, strict=False, **kwargs):
"""Create and register a model."""
def schema_model(self, name=None, schema=None):
"""Create and register a schema model."""
def extend(self, name, parent, fields):
"""Extend model with additional fields (deprecated)."""
def clone(self, name, *specs):
"""Clone model with additional fields."""
def inherit(self, name, *specs):
"""Create inherited model."""
@property
def path(self):
"""Namespace URL path."""
@property
def parser(self):
"""Request parser instance."""
@property
def payload(self):
"""Current request payload."""Usage Examples
Basic API Setup
from flask import Flask
from flask_restx import Api, Resource
app = Flask(__name__)
api = Api(
app,
version='1.0',
title='My API',
description='A comprehensive REST API'
)
@api.route('/health')
class HealthCheck(Resource):
def get(self):
return {'status': 'healthy'}Using Namespaces
from flask_restx import Namespace
# Create namespace
users_ns = api.namespace('users', description='User operations')
@users_ns.route('/')
class UserList(Resource):
def get(self):
return {'users': []}
def post(self):
return {'message': 'User created'}, 201
@users_ns.route('/<int:user_id>')
class User(Resource):
def get(self, user_id):
return {'user_id': user_id}Advanced Configuration
# API with extensive configuration
api = Api(
app,
version='2.0',
title='Advanced API',
description='API with comprehensive configuration',
doc='/docs/', # Custom documentation path
catch_all_404s=True, # Handle 404s with API error handler
validate=True, # Enable validation by default
authorizations={
'Bearer': {
'type': 'apiKey',
'in': 'header',
'name': 'Authorization'
}
}
)Install with Tessl CLI
npx tessl i tessl/pypi-flask-restx