When planning the REST API, I initially thought that a ResponseFactory with a single method, returning an empty response, would be sufficient. Handlers could modify this response object to achieve any goal. The problem with this, immediately apparently when I started writing code, was that handler authors shouldn't be asked to format every response from scratch. There needs to be a policy framework which makes it easier to generate standard or preferred kinds of responses. ResponseFactory itself could be this policy framework, providing various methods for creating pre-filled responses.
Writing ResponseFactory thus requires us to answer several of the questions I asked on T221177:
- What should standard responses look like? For example, standard 404s and parameter validation errors. Should they be JSON? Localised?
- What sorts of responses will endpoints typically need?
- Is ResponseFactory responsible for localisation?
- Do iteration/index routes require any special handling?