Stabilize API models

[r-c-n]

I don't really know if the API models are final or not, but from what I saw I think there are still some parts that aren't fully stabilized.

Since there'll be a point where the API design won't accept any more changes that may break compatibility, I think it's crucial to collect enough use cases from external feedback in order to refine and solidify the parts of the models that are still in progress, and then consolidate it in an API documentation.

[gctucker]

The 4th December milestone is when we should have a release candidate, and that's when we should stop making changes to the API, models and anything without measures in place to ensure continuity. That's basically when API v1 should be created (maybe v1-rc1 initially...), same thing for the kernelci Python package etc. Then changes that just add things and remain backwards-compatible can happen pretty easily, but changes that "break" things will need a deprecation phase, database migrations, release notes and everything you would expect from a stable system and software packages.

[gctucker]

I'm referring to this milestone: https://kernelci.org/blog/posts/2023/api-timeline/#production-deployment

[gctucker]

There are or should be GitHub issues associated with the milestone too about this, maybe it's a bit implicit in some cases. Ultimately the design checklist should be used to verify that all the things that can change have been reviewed and have stopped changing prior to that milestone: #352

Please note that the design checklist mentions the data models used at the API level, which is not necessarily the same as what is stored in the database. Internal API models might change more easily if they don't have any direct impact on the users, just so far we've basically be using them directly with the API endpoint "signatures" (actual type inference is used here with FastAPI). A typical example for this distinction is for user profiles, we might have a public model and a private one with the hashed password and other things that shouldn't be exposed.