Skip to content

Add documentation on creating and using service classes #5741

Open
@mcmire

Description

@mcmire

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions