Configuration¶
Intro¶
In flarchitect, configuration options are essential for customizing the API and its accompanying documentation.
These settings can be provided through Flask config values or directly within SQLAlchemy model classes using Meta classes.
Beyond the basics, the extension supports hooks and advanced flags for post-serialization callbacks, rate limiting, field exclusion, blueprint naming, endpoint naming via API_ENDPOINT_NAMER, soft deletion, and per-method documentation summaries.
Flask config values offer a straightforward, standardized way to modify the extension’s behavior at a global or model level.
Config Hierarchy¶
To offer flexibility and control, flarchitect follows a hierarchy of configuration priorities:
Lowest Priority – Global Flask config options apply to all requests and are overridden by any more specific configuration.
Method-based – Method-specific options can override global settings for particular HTTP methods.
Model-based – SQLAlchemy model
Metaattributes override both global and method-based configurations.Highest Priority – Model-specific configurations suffixed with an HTTP method allow the most detailed customization per model and method.
Note
When applying config values:
Global Flask config values are prefixed with
API_.Global method-based Flask config values are prefixed with
API_{method}_.SQLAlchemy model config values omit the
API_prefix and are lowercase.SQLAlchemy model method config values omit the
API_prefix, are lowercase, and are prefixed with the method.
Config Value Structure¶
Every configuration value has a specific structure that defines where it can be used and how it should be written. These structures are indicated by the badges in the configuration tables next to each value.
Please note the badge for each configuration value, as it defines where the value can be used and how it should be written.
Global
Global configuration values are the lowest priority and apply to all requests unless overridden by a more specific configuration.
They are applied in the Flask config object and are prefixed with API_.
These settings are ideal for defining application-wide defaults such as API metadata, documentation behaviour,
or pagination policies. Any option listed in the configuration table can be supplied here using its
global API_ form (for example API_TITLE or API_PREFIX) and may accept strings, integers,
booleans, lists, or dictionaries depending on the option.
Use this level when you need a single setting to apply consistently across all models and methods.
Example:
class Config:
API_TITLE = "My API" # text shown in documentation header
API_PREFIX = "/v1" # apply a versioned base route
API_CREATE_DOCS = True # generate ReDoc documentation
See the Global page for more information.
Global Method
Global configuration values can apply to specific HTTP methods: GET, POST, PUT, DELETE, or PATCH.
The method name should be added after the API_ prefix.
Use method-scoped options to change behaviour between reads and writes across the entire API, such as
applying tighter rate limits to mutating requests or disabling a verb globally. Any global configuration
key that supports method scoping can be used here by inserting the method name (e.g. API_GET_RATE_LIMIT),
with value types mirroring their global counterparts.
Example:
class Config:
API_GET_RATE_LIMIT = "100 per minute" # throttle read requests
API_POST_BLOCKED = True # disable POST across the API
API_PATCH_RATE_LIMIT = "10 per minute" # tighter limits on writes
See the Global Method page for more information.
Model
Model configuration values override any global Flask configuration.
They are applied in the SQLAlchemy model’s Meta class, omit the API_ prefix, and are written in lowercase.
Configure this level when a single model requires behaviour different from the rest of the application,
such as marking a model read only, changing its serialization depth, or blocking specific methods.
Options correspond directly to the global keys but in lowercase without the prefix (for example rate_limit
or pagination_size_default) and accept the same data types noted in the configuration table.
Example:
class Article(db.Model):
__tablename__ = "article"
class Meta:
rate_limit = "10 per second" # API_RATE_LIMIT in Flask config
pagination_size_default = 10 # API_PAGINATION_SIZE_DEFAULT
blocked_methods = ["DELETE", "POST"] # API_BLOCK_METHODS
See the Model page for more information.
Model Method
Model method configuration values have the highest priority and override all other configuration.
They are applied in the SQLAlchemy model’s Meta class, omit the API_ prefix, are lowercase, and are prefixed with the method.
Use these settings to fine-tune behaviour for a specific model-method combination. This is useful when,
for example, a model should allow GET requests with a high rate limit but restrict POST calls or
customise serialization only for PATCH. Any model-level option can be adapted by prefixing it with the
HTTP method name (such as get_rate_limit or post_blocked) and follows the same value types as the
corresponding model option.
Example:
class Article(db.Model):
__tablename__ = "article"
class Meta:
get_rate_limit = "100 per minute" # API_GET_RATE_LIMIT
post_blocked = True # API_POST_BLOCKED
patch_serialization_depth = 1 # API_PATCH_SERIALIZATION_DEPTH
See the Model Method page for more information.
Cascade delete settings¶
See Cascade deletes in the advanced configuration guide for usage examples of
API_ALLOW_CASCADE_DELETE, API_ALLOW_DELETE_RELATED and
API_ALLOW_DELETE_DEPENDENTS.
Complete Configuration Reference¶
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|