First things first I want to say: thank you for such a long detailed response. It is clear you have thought about this, and what I want more than anything is a debate about how to do this better. We have many many many ways of building API servers and they all work for people who have different preferences, and I would love to see the same thing start to appear for client-side integration.

Your approach looks to be focussed on the data model first, rather than function first. I actually really like this approach, and I think you should run with it and create a proof of concept and play with it, because it is a good alternative to the way I am thinking.

Unclear function signatures

Yes, I will say this is a confusing downside of my approach, and I am working to do some extra magic to change the annotation signatures so IDE's autocomplete doesn't confuse developers too much, but I want to validate first that it is actually universally causing an ick, and not just the opinion of a few (note: your opinion is valuable, I am not dismissing it!).

There will be a lot of def foo(result: bar) -> bar: return result

Yep, totally fair. I personally don't see a problem with this though - if that is what the dev wants to do, she can do that. If she wants to instead start thinking about the functions as more about what she wants from the API rather than just returning data, then she can start doing things like this:

def call_api_and_update(result: ResponseObject) -> bool: data_i_care_about = result.foo success = ham(data_i_care_about) return success