Handle validation, errors, and business logic in the API consistently

[kgodey]

Problem

Currently, we have validation, error handling, and business logic spread across the db module, models, viewsets, and serializers to make the API work. This is confusing to work with.

Proposed solution

• Organize the code with a clear separation of concerns.
• Document how the code is organized for reference.

Additional context

Related to:

• Reorganize code in db and set some standards for imports #582
• Define common error structure #560
• Spec for a better way to pass data between service layer and data layer #823

[silentninja]

Few suggestions to handle errors.

1. Extending ApiException - This could allow us to raise exceptions other than validation errors
2. Using context managers - This is more Java-esque, but should suit our usecase well though as we have similar error handling in viewsets and would help in capturing non API errors from other modules and converting them in an appropriate API response

[mathemancer]

I like the context manager setup, but I don't see how it's exclusive with the ApiException idea.

[silentninja]

ApiException is limited to Django rest and cannot be used outside the service layer, while context manager is useful for capturing Custom errors imported from other modules and converting it into a proper API error with custom status codes

[dmos62]

I feel good about using context managers for error handling.

[kgodey]

Now that we have a larger backend team, I think it would be good for whoever takes this issue to write up a technical spec and get it reviewed before proceeding with the refactor.

[mathemancer]

One thing to keep in mind when speccing this out is that assuming multiple context managers that we'd want to potentially combine to catch different groups of exceptions (for example, we could have one exclusive to the Django part of the code that just deals in the APIException children), we'll need to think a bit about how to make them compose associatively and (hopefully) symmetrically. We don't want to have different exceptions and messages depending on the order in which context-management decorators are applied.

• We could try to ensure that there's never any overlap between two, but I don't think that's feasible (also, we may well want to catch a parent exception with a more general message if a child exception doesn't match, and these could be in separate wrappers).
• We could also require all such composition be done inside another decorator, and only allow applying one exception handling decorator to a given function, so we avoid ad-hoc combinations that could produce different results.

[kgodey]

@silentninja I assigned this to you based on the conversation in #883.