[BUG] - API Endpoints Don't Return Response Models

[zdomke]

Describe the bug

Majority, if not all, of our api endpoints for the backend (app/api/v1/*.py) do not make use of our Pydantic models for responses (app/schemas/*.py). Instead, they are described as returning a dict. While this works and it isn't inaccurate, we do have the ability to be more specific.

On major benefit we get from using our Pydantic models (that we already have made) is the documentation. FastAPI autogenerates docs for us using OpenAPI and Swagger. These tools use the type-hinted return type to populate the documentation with decent examples of responses for each endpoint.

Expected behavior

We should always be returning a Pydantic model. The only possible exemption would be if we are returning very primitive data.

For example, endpoints that return a count may want to list their return type as ints instead of wrapping it in a response model.
Or maybe not, idk.

Steps to Reproduce

1. Start up the backend using docker
2. Navigate to the docs pages
   a. OpenAPI: http://localhost:8080/docs/
   b. Swagger: http://localhost:8080/redoc/
3. Find an endpoint and read the documentation on it
4. Notice that the "Response" section does not give a detailed example

Possible solution (optional)

Replace the return type for our endpoints with the response models defined in app/schemas/*.py.

If you don't have a response model, one will be provided for you (or you gotta make them, I don't make the rules ¯\_(ツ)_/¯ ).

My platform

No response

Additional context

Method returns dict

Method returns Pydantic Model

[zdomke]

Oh, a couple of side notes about these response models stored in app/schemas/*.py:

• The naming convention is odd. We are frequently appending class names with DTO, but that doesn't tell us if it's expected to come in or out. We could instead append them with Request or Response so we know how they relate to our backend.
  • In fact, some response models are already doing this, see the health response models in app/api/v1/health.py (ignoring the fact that these are defined in the wrong file. I fixed that in ENH: Add Authorization Based on API Keys #31)
• These Pydantic models are being imported oddly. They are all imported in app/schemas/__init__.py but no file references the submodule, instead they reference the python files themselves. See examples below:
  

  react-squirrel-backend/app/services/pv_service.py

  Lines 4 to 6 in 8dee0ed

  	from app.schemas.pv import PVElementDTO, NewPVElementDTO, UpdatePVElementDTO
  	from app.schemas.tag import TagDTO
  	from app.schemas.common import PagedResult

[zdomke]

Turns out that the frontend is requiring these weird wrapped DTOs. We should avoid the whole wrapping/unwrapping strategy altogether.