In order to know which controller a request should go to, src/spiffworkflow_backend/api.yml is used by the connexion library.
For example, in api.yml, a GET of /status is mapped to spiffworkflow_backend.routes.health_controller.status, where status is a function in health_controller.py.
Controllers can use services (preferred) and models (allowed) to do their work, but they can never use another controller.
### Services
Services are where most of the business logic lives.
Services can use other services, but the direction of usage must be in one way.
If serviceA uses serviceB, then serviceB cannot use serviceA.
Services are allowed to use models, but models are not allowed to use Services.
Services cannot use controllers.
Keeping calls flowing in a single direction makes things easier to understand and avoids circular imports.
- avoid json.dumps when you are creating json. use jsonify (a flask thing) instead
- avoid marshmallow when possible and instead use @dataclass on your model
- if you need to represent your object in a very custom way (the default dataclass columns are not working out), write a method called serialized on your model (this is used by the default serializer)
Do not define BlahError (exceptions) inside other classes.
All exception classes should be defined in 1) one file, if there are not too many or 2) files that contain only other exception class definitions, again to avoid circular imports.
