Skip to content

Add documentation on creating and using service classes #5741

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mcmire opened this issue Apr 30, 2025 · 0 comments
Open

Add documentation on creating and using service classes #5741

mcmire opened this issue Apr 30, 2025 · 0 comments

Comments

@mcmire
Copy link
Contributor

mcmire commented Apr 30, 2025

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

Prerequisites

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant