Configuration#
Intro#
In flarchitect, 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, flarchitect
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.
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 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():
TITLE="My API"
See the Global page for more information.
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():
GET_RATE_LIMIT="100 per minute"
POST_RATE_LIMIT="10 per minute"
PATCH_RATE_LIMIT="10 per minute"
See the Global Method page for more information.
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 RATE_LIMIT in flask config
rate_limit = "10 per second"
# config value is shown as BLOCK_METHODS in flask config
blocked_methods = ["DELETE", "POST"]
See the Model page for more information.
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 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#
default: type 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. |
default: type Optional Global |
The url for accessing the ReDoc documentation. |
default: type 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. |
default: type Required Global |
Sets the version number of your API. This value will appear in the generated ReDoc documentation and in api responses when DUMP_VERSION is enabled.
|
default: type Optional Global |
When defined, a logo will be displayed in the ReDoc documentation. This should be be valid image URL |
default: type Optional Global |
Paired with LOGO_URL, this value sets the background color of the logo in the ReDoc documentation. This value should be a valid CSS color value. |
default: type 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 View the template file here |
default: type Optional Global |
Configures the font style for your ReDoc documentation, with This setting allows for visual customization to match your documentation’s aesthetic preferences. |
default: type 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. |
default: type 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. |
default: type 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. |
default: type 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. |
default: type 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. |
default: type 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:
|
default: type Optional Global |
Custom CSS or JS to be added to the ReDoc documentation. Example: <style>
.redoc-section h1 {
color: red;
}
</style>
|
default: type Optional Global |
Controls the verbosity of flarchitect’s output to console, choose a value between 0 and 4. 0 being no output and 4 being the most verbose. |
API Configuration Values (MAIN)#
default: type Optional Global |
When enabled, the API will print exceptions to the console when they occur. This is useful for debugging purposes. |
default: type Optional Global |
When enabled, the API will include a |
default: type Optional Global |
When enabled, the API will include a |
default: type Optional Global |
When enabled, the API will include a The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE. |
default: type Optional Global |
When enabled, the API will include a The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE. |
default: type Optional Global |
When enabled, the API will include a The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE. |
default: type Optional Global |
When enabled, the API will include a The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE. |
default: type Optional Global |
When enabled, the API will include a The output key will either be camelCase or snake_case depending on the value of CONVERT_TO_CAMEL_CASE. |
default: type Optional Global |
When enabled, the API will include a |
default: type Required Global |
The base class for all models in the API, and a required configuration value. Used by flarchitect to correctly analyse models and automatically create endpoints.
When using Flask-SQLAlchemy
you must subclass your models with
|
default: type Optional Model Method |
When enabled, the API will include hybrid properties in resources response data & in the ReDoc documentation. |
default: type 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. |
default: type 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. |
default: type 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 |
default: type 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
|
API Callbacks#
default: type 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.
|
default: type 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. |
default: type 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.
|
default: type 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.
|
default: type 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.
|
API Method Config (Delete)#
default: type Optional Model Method |
When enabled, the API will allow the user to specify models to delete along with the model being queried.
When disabled, the API will not allow these operations and will raise a 409 error if the user attempts to do so, signalling that the operation is not allowed along with a message of the offending related model(s). Note Setting the cascade delete options on your models, is the best way to control this behavior. |
default: type Optional Model Method |
When enabled, the API will recursively attempt to delete all dependents of the model being queried.
Its possible however, some fringe cases have not been accounted for and the operation may fail. In this case it is always best to set the cascade delete options on your models to control this behavior. When disabled, the API will not allow these operations and will raise a 400 error if the user attempts to apply the query parameter. Note Setting the cascade delete options on your models, is the best way to control this behavior. |
default: type Optional Global |
When enabled, the API will soft delete records from the database. Soft
deleting will mark a record as deleted
in a user specified column, rather than actually deleting the record from
the database. Users can show deleted
records with the query parameter |
default: type Optional Global |
The model attribute name that hold the soft delete value. This value
should be ideally set in your base model
and can be any type, but for ease boolean is recommended. i.e |
default: type Optional Global |
A tuple that represents the |
Schema Configuration Values#
default: type Optional Global |
At the heart of flarchitect is the
|
default: type Optional Global |
One of the following options: 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. |
default: type Optional Global |
One of the following options: |
default: type Optional Global |
When enabled, the API will include a |