I was going to propose that the API was a hook, so the "request and response format" is just the method parameters and return value for hook.

Back from the original spec, I was thinking something of the format of FragmentProvider::renderFragmentFromWikitext( string $input ): ?ParserOutput and FragmentProvider::renderFragmentsFromWikitext( string[] $inputs ): ?ParserOutput[] (or if it must be a hook, onRenderFragmentFromWikitext( string $input ) etc.? Though that's rather bare-bones and makes it hard to distinguish errors from timeouts from not-ready-yet statuses, and doesn't specify latency/etc.

My proposal replaces the string in your hook with a FragmentType object; WIP is at https://gerrit.wikimedia.org/r/c/mediawiki/services/parsoid/+/821282. That will eventually allow for nested invocations. Right now ParserOutput is the way we write "fragment plus metadata", although the "fragment" part (as opposed to the "HTML string") is WIP. So:

FragmentProvider::renderFragmentFromWikitext( FragmentType[] $arguments ): ParserOutput|Placeholder

The `Placeholder' might be a singleton for now, but might eventually be a place to store the expected time until the value is ready (ie cache ttl) and/or a UUID that lets the fragment provider call back when the fragment is ready, etc.

LGTM. In discussion yesterday, Subbu, Arlo and I thought that we might want to return in the "not ready yet" / placeholder concept some meta-data for the parser about how long to expect to wait before trying again (for WF, ~5 seconds; for TimedMediaHandler, maybe ~60mins).