FAQ

Can I change the case of the output?

By default URL endpoints are pluralised kebab-case, resources are camelCase and resource fields are snake_case.

You can change the default behaviour easily by adding the below global Flask configurations:

Options are: camel, pascal, snake, kebab, screaming_kebab, screaming_snake

When should I run BumpWright to bump the version?

Make your code changes and commit them first. Then run bumpwright auto --commit --tag to let BumpWright determine the next version and record it in a separate commit (and optional tag). Finally, push both the feature commit and the bump commit, along with any tags, to your remote repository.

What do the BumpWright commands do?

  • bumpwright decide inspects your recent commits or API differences and reports the release type without modifying any files.

  • bumpwright bump increments the version. Add --dry-run to preview the change before writing.

  • bumpwright auto combines deciding and bumping into a single command, ideal for most release workflows.

Can I block HTTP methods in my API?

HTTP methods can be blocked easily, on a global or a model level. See here for full information on how to block methods.

Example blocking all DELETE and POST methods:

app.config['API_BLOCK_METHODS'] = ['DELETE', 'POST']

Example blocking DELETE and POST methods on a specific model:

class MyModel(Model):
    class Meta:
        block_methods = ['DELETE', 'POST']

Alternatively, if you want to only allow GET requests you can turn on the API_READ_ONLY option in the Flask configuration, which will block all but GET requests from being served.

Can I extend the functionality of the API?

If you need to perform some custom logic or actions, you can use callbacks. Callbacks are functions that fire:

  • before the database query is performed

  • before the data is returned to the API

  • on an exception being raised

See the below configuration values that can be defined globally as Flask configurations or on a model level.

I use soft deletes, what can I do?

If you need to perform soft deletes, you can use the API_SOFT_DELETE configuration as a Flask global configuration. See Soft delete for an example.

Additional configuration values are needed to specify the attribute storing the delete flag and the values representing the active and deleted states. See the below configuration values that can be defined globally as Flask configurations or on a model level.

Can I generate an OpenAPI specification document?

Yes. When API_CREATE_DOCS is enabled the schema is automatically generated at start-up and served at /openapi.json (and under the docs UI at /docs/apispec.json). See API Documentation for examples on exporting or customising the document.

How do I update documentation after adding new models?

Restart your application. The specification is rebuilt on boot and will include any newly registered models or routes.

Troubleshooting

The documentation endpoint returns 404

Ensure API_CREATE_DOCS is set to True and that the flarchitect.Architect has been initialised. If you mount the app under a prefix, check documentation_url_prefix.

A route is missing from the spec

Confirm the model has a Meta class and the endpoint isn’t blocked by API_BLOCK_METHODS. Rebuilding the application will refresh the specification.