As we're working on the common schemas for common entities in MW REST API responses, we could introduce an MW service, RESTEntityFormatter (name TBD). The service would have methods for serializing common MW entities (RevisionRecord, UserIdentity etc) into defined schemas.
The service could be injected into handlers when needed and would contain the collection of formatter functions, like formatRevision( RevisionRecord $rev), returning an JSON-strigifyable array according to the specified schema.
Complications to consider:
- Formatters for some of the entities might depend on more services. For example, to format a revision and calculate a 'delta' we might need RevisionLookup to fetch the parent revision. Perhaps splitting formatters into separate classes would allow us to have less dependencies.
- Sometimes formatters can be optimized by the context that's already known in a handler. Example: revision 'delta' property can be calculated with less queries if the whole list of revisions is being processed. We could make the formatters have formatRevisionList method, but it's quite ugly..
What do you think? The output of this task would be a decision of whether we want to do something like this or not, and how do we want to do it.