Configuration

Intro

In Flask-Scheema, configuration options play a crucial role in customizing the behavior of API and its accompanying documentation. These configurations can be specified through Flask config values or directly within SQLAlchemy model classes using Meta classes.

Flask config values are the most straightforward way to configure the API. Offering a standardized approach to modifying the extension’s behavior at a global or model level.

Config Hierarchy

To offer flexibility and control, Flask-Scheema adheres to a hierarchy of configuration priorities.

• Lowest Priority - At the base of this hierarchy are the global Flask config options, applied globally to all requests. These values will be overridden by more specific configurations.

• Method based configurations can be applied to the global Flask config, allowing for more precise control over the behavior of the API in response to specific HTTP method.

• Model based configurations can be embedded within SQLAlchemy model classes through Meta class attributes, allowing for more fine-grained control over the behavior of the API in response to specific models.

• Highest Priority - Finally the highest precedence is given to model-specific configurations suffixed with a HTTP method, allowing for the most detailed customization of the API’s behavior per model and HTTP method.

Note

When applying config values

• Global Flask config values are prefixed with API_.

• Global Flask method based config values are prefixed with API_{method}_.

• SQLAlchemy Model config values omit the API_ prefix and are lower case.

• SQLAlchemy Model method based config values omit the API_ prefix, are lower case and are prefixed with the method.

Note

Each configuration value below is assigned a tag, which will define where the value can be used and which priority it takes.

Pri 1. Model Method - View here

Pri 2. Model - View here

Pri 3. Global Method - View here

Pri 4. Global - View here

Config Value Structure

Every configuration value has a specific structure that defines where it can be used and how it should be written. These are defined by the the below badges which are listed in the configuration value tables next to each value.

Please take note of the badge for each configuration value, as this will define where the value can be used and how it should be written.

Global

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 class and are prefixed with API_.

Example Flask config value:

class Config():

    API_TITLE="My API"

See the Global page for more information.

Global Method

Global Method

Global configuration values can apply globally to specific HTTP method, GET, POST, PUT, DELETE, PATCH.

The method should be added after the API_ prefix.

Example Flask config value:

class Config():

    API_GET_RATE_LIMIT="100 per minute"
    API_POST_RATE_LIMIT="10 per minute"
    API_PATCH_RATE_LIMIT="10 per minute"

See the Global Method page for more information.

Model

Model

Model configuration values override any Flask configuration.

They are applied in the SQLAlchemy models Meta class, they should omit the prefix API_ and be written in lower case.

Example model.Meta config value:

class MyModel(db.model):
    __table__ = "my_model"

    class Meta:
        # config value is shown as API_RATE_LIMIT in flask config
        rate_limit = "10 per second"
        # config value is shown as API_BLOCK_METHODS in flask config
        blocked_methods = ["DELETE", "POST"]

See the Model page for more information.

Model Method

Model Method

Model method configuration values have the highest priority and will override any other configuration.

They are applied in the SQLAlchemy models Meta class, they should omit the prefix API_, be written in lower case and be prefixed with the method.

Example model.Meta config value:

class MyModel(db.model):
    __table__ = "my_model"

    class Meta:
        # config value is shown as API_RATE_LIMIT in flask config
        get_rate_limit = "10 per minute"
        post_rate_limit = "5 per minute"

See the Model Method page for more information.

Documentation Configuration Values

CREATE_DOCS default: True type bool Optional Global	Controls whether the Redoc documentation is created and served by the API. When disabled, the API will not serve documentation. If true, the API will serve documentation at the url specified by DOCUMENTATION_URL.
DOCUMENTATION_URL default: /docs type str Optional Global	The url for accessing the ReDoc documentation.
TITLE default: None type str Required Global	Sets the title of your API in the generated ReDoc documentation. It appears prominently in the documentation, serving as a headline for users exploring your API.
VERSION default: None type str Required Global	Sets the version number of your API. This value will appear in the generated ReDoc documentation and in api responses when API_DUMP_VERSION is enabled. Example: 0.1.0
LOGO_URL default: None type str Optional Global	When defined, a logo will be displayed in the ReDoc documentation. This should be be valid image URL
LOGO_BACKGROUND default: None type str Optional Global	Paired with API_LOGO_URL, this value sets the background color of the logo in the ReDoc documentation. This value should be a valid CSS color value.
DESCRIPTION default: ./flask_scheema/html/base_readme.MD type str Optional Global	The main description of the API in the generated ReDoc documentation. This value should be a valid markdown string or a path to a markdown file. The file will be rendered with Jinja and you can access the Flask config with the {{ config }} variable. View the template file here
DOCS_FONT default: jetbrains_mono type str Optional Global	Configures the font style for your ReDoc documentation, with jetbrains_mono as the default. Options include jetbrains_mono, sourcecode_pro, roboto, montserrat, lato or any valid css font. This setting allows for visual customization to match your documentation’s aesthetic preferences.
CONTACT_NAME default: None type str Optional Global	Specifies the contact name for inquiries and support in the ReDoc documentation. If not provided, the field name will not be displayed in the docs.
CONTACT_EMAIL default: None type str Optional Global	Specifies the contact email for inquiries and support in the ReDoc documentation. If not provided, the field name will not be displayed in the docs.
CONTACT_URL default: None type str Optional Global	Specifies the contact web address for inquiries and support in the ReDoc documentation. If not provided, the field name will not be displayed in the docs.
LICENCE_NAME default: None type str Optional Global	Specifies the licence type for the API in the ReDoc documentation. If not provided, the field name will not be displayed in the docs.
LICENCE_URL default: None type str Optional Global	Specifies a url to the licence type for the API in the ReDoc documentation. If not provided, the field name will not be displayed in the docs.
SERVER_URLS default: None type list[dict] Optional Global	Specifies the server(s) used for calling the API in the ReDoc documentation. If not provided, the field name will not be displayed in the docs. Example structure: [{“url”: “https://api.example.com”, “description”: “Main server”}, …]
CUSTOM_HEADERS default: None type str Optional Global	Custom CSS or JS to be added to the ReDoc documentation. Example: <style> .redoc-section h1 { color: red; } </style>
VERBOSITY_LEVEL default: 0 type int Optional Global	Controls the verbosity of flask-scheema’s output to console, choose a value between 0 and 4. 0 being no output and 4 being the most verbose.

API Configuration Values

PRINT_EXCEPTIONS default: True type bool Optional Global	When enabled, the API will print exceptions to the console when they occur. This is useful for debugging purposes.
DUMP_DATETIME default: True type bool Optional Global	When enabled, the API will include a datetime field in the response data. This field will contain the current date and time of the response.
DUMP_VERSION default: True type bool Optional Global	When enabled, the API will include a version field in the response data. This field will contain the version number of the API.
DUMP_STATUS_CODE default: True type bool Optional Global	When enabled, the API will include a statusCode field in the response data. This field will contain the status code of the response. The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE.
DUMP_RESPONSE_TIME default: True type bool` Optional Global	When enabled, the API will include a responseTime field in the response data. This field will contain the time taken to process the request in ms. The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE.
DUMP_COUNT default: True type bool Optional Global	When enabled, the API will include a totalCount field in the response data. This field will contain the total number of records available to be queried with pagination (not the number of records returned in the response). The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE.
DUMP_NULL_NEXT_URL default: True type bool Optional Global	When enabled, the API will include a nextUrl field in the response data if null. When disabled the nextUrl field will not be included in the response data if null. The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE.
DUMP_NULL_PREVIOUS_URL default: True type bool Optional Global	When enabled, the API will include a previousUrl field in the response data if null. When disabled the previousUrl field will not be included in the response data if null. The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE.
DUMP_NULL_ERRORS default: False type bool Optional Global	When enabled, the API will include a error field in the response data if null. When disabled the error field will not be included in the response data if null.
BASE_MODEL default: None type DeclarativeBase Required Global	The base class for all models in the API, and a required configuration value. Used by flask-scheema to correctly analyse models and automatically create endpoints. This value should be a valid base model (see here). When using Flask-SQLAlchemy you must subclass your models with db.Model as normal, and also populate this field with db.Model. You will, however, have to pass your actual base model to the SQLAlchemy.init_app(base_clas=YourBase) View the Quickstart docs for more information on how to use this value.
ALLOW_CASCADE_DELETE default: True type bool Optional Model Method	When enabled, the API will allow cascade delete operations on models when the query parameter ?cascade_delete=1 is added to the request. If this parameter is not added, the API will return a 400 response (when the model has dependent relationships). When disabled, the API will not allow cascade delete operations on models and will return a 400 response (when the model has dependent relationships).
SETUP_CALLBACK default: None type callable Optional Model Method	When assigned, the API will call the function prior to the model being queried. This is useful for adding custom logic to the API, such as adding additional query parameters/modifying the query or logging request to the database. View an example function & its signature here.
POST_DUMP_CALLBACK default: None type callable Optional Model Method	When assigned, the API will call the function after the model has been dumped to a dictionary by Marshmallow. Its possible to add extra validation here or modify the response data. View an example function & its signature here.
RETURN_CALLBACK default: None type callable Optional Model Method	When assigned, the API will call the function post database call and pre returning the data to the client. This is useful for adding custom logic to the API, such as modifying the response data or logging the response to the database. View an example function & its signature here.
ERROR_CALLBACK default: None type callable Optional Global Method	When assigned, the API will call the function when an error occurs. This is useful for adding custom logic to the API, such as logging the error to the database, sending an emails etc. View an example function & its signature here.
ADDITIONAL_QUERY_PARAMS default: None type list[dict] Optional Model Method	If you are hoping to extend the default query parameters of the API using callbacks, you may also want to add these to the ReDoc documentation. This value allows you to add additional query parameters per model or globally to the API. View an example of its use and expected value here Example of its use here.
DUMP_HYBRID_PROPERTIES default: True type bool Optional Model Method	When enabled, the API will include hybrid properties in resources response data & in the ReDoc documentation.
ADD_RELATIONS default: True type bool Optional Model	When enabled, the API will automatically add relationships to the model’s schema. This is useful for automatically including related resources in the response data.
IGNORE_UNDERSCORE_ATTRIBUTES default: True type bool Optional Model Method	When enabled, the API will ignore all attributes that start with an underscore in the model. This is useful for hiding private attributes from the API.
PAGINATION_SIZE_DEFAULT default: 20 type int Optional Global	The default number of records to return in a single response. This value can be overridden by the client by adding the query parameter ?limit= to the request. The maximum value for this parameter is defined by PAGINATION_SIZE_MAX.
PAGINATION_SIZE_MAX default: True type bool Optional Model Method	The maximum number of records to return in a single response. The default (no query parameter) is defined by PAGINATION_SIZE_DEFAULT. Adding the query parameter ?limit= to the request allows the user in increase this default but it is limited to this value as the maximum allowed to be returned. Increase this value to allow more records to be returned in a single response.

Schema Configuration Values

BASE_SCHEMA default: AutoSchema type Schema Optional Global	At the heart of flask-scheema is the AutoSchema which creates and translates your SQLAlchemy models into Marshmallow schema’s. This value should be a valid schema class (see here). It is advisable to leave this value as the default, unless you have a specific use case or know what you are doing.
ENDPOINT_CASE default: kebab type str Optional Global	One of the following options: camel, pascal, snake, screaming_snake, kebab or screaming_kebab. Defines which case to use to convert the model names into endpoint URLs. To keep inline with restful API conventions, the endpoint URL will also be pluralized.
FIELD_CASE default: snake type str Optional Global	One of the following options: camel, pascal, snake, screaming_snake, kebab, screaming_kebab. This value will be used to convert the model attributes into field names.
SCHEMA_CASE default: camel type str Optional Global	When enabled, the API will include a datetime field in the response data. This field will contain the current date and time of the response.