Stabilize API models

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.

The issue names no files, tests, or entry points; begin by reviewing the current API models and gathering the external use cases referenced here. Done means the remaining model changes are decided and the resulting API design is consolidated in API documentation.

Written by the indexing model from the issue text.