Open
Description
Currently, teams are using outdated patterns, such as handleFetch
from controller-utils
, to make HTTP requests within controller packages. The service class pattern is superior to this approach, because it allows engineers to:
- automatically retry failed requests
- pause for a period of time if the API is down before retrying again
- easily implement other patterns such as batching
- prevent clients from needing to adapt to breaking changes in APIs
- use the messenger to make HTTP requests within UI components in the same way that controllers would
We should add proper guidance for teams.
Acceptance Criteria
- A guide on service classes exists in
docs/
that covers:- Why service classes are preferred over simple functions
- How to create a service class
- Why creating an abstract type is important
- How to use
createServicePolicy
in service classes that make HTTP requests
- How to use the service class in a controller
- How to expose methods of the service through the messenger
- Guidelines exist in the "Writing Controllers" document that advises engineers to use service classes, and links to the Service Classes guide