I know that Fred's post does not contain a complete working prototype of a whole system. Such prototypes are very useful, it is great that you have made them, and I need to find time to study them.
However, what I was trying to say is that small snippets of code, showing particular aspects of the system, really help the explanation. After all, the key things is how this new API looks to users. So, just like we make UI mock-ups in the tracker to quickly make it clear what were are talking about when designing a new bit of Moodle functionality, we need something similar here. API are the 'user-interface' that third-party developers user to interact with Moodle, and it should be possible to present a quick sketch of the key things like:
- I am making a plugin, and I want to output a user picture.
- I am a themed and I want to change how the user picture is displayed.
- I am making a plugin, and I want to define a new thing like a forum post that can be displayed.
Sure, there also needs to be a lot of clever back-end code to make what is shown in the mock-ups work, but that is an implementation detail, and only a few people need to understand that. Many people will need to work with the public face of this in future, so that is why it is worth showing small snippets that mock-up how that will look.