Skip to content

Alpha Release: Add Service schema/endpoint to API #94

@clundie-CL

Description

@clundie-CL

Problem description
The current NAM API lacks a Service model and associated endpoints. This creates ambiguity in flows where API Consumers must target a specific subscription context, especially when a subscriber has multiple services (e.g., multiple MDUs for a property manager, primary + secondary homes, or mixed commercial/residential accounts).

Today, Trust Domain creation implicitly relies on device/service-site scoping, which does not reliably map to the subscriber’s service structure across operators. This causes three main issues:

  • API Consumers cannot explicitly specify which service a Trust Domain belongs to.
  • There is no consistent method for discovering the service(s) tied to the identity_token, nor for resolving ambiguity when multiple services exist.
  • There is no place to anchor service-scoped capability discovery, which is becoming necessary as device-level capabilities diverge from service-level policy.

This gap limits interoperability across operators and complicates integration scenarios like third-party property-management apps.

Possible evolution
Introduce a Service schema and corresponding endpoints, enabling:

  • Explicit Service selection when creating Trust Domains (e.g., serviceId required in create requests).
  • Service discovery for subscribers with multiple active services, based on token context.
  • Service-level capability discovery endpoints (e.g., /services/{serviceId}/capabilities).
  • A consistent workflow where all higher-level configuration resources—Trust Domains, NetworkAccessDevices, Reboot operations—are anchored to an unambiguous service.

This evolution would provide a stable abstraction layer above service sites and devices, ensuring consistent behavior across operators’ OSS/BSS implementations.

Alternative solution
Overload the existing ServiceSite model to act as a proxy for “service,” adding metadata or disambiguation rules. However, this is brittle because:

  • ServiceSites represent physical locations, not commercial subscriptions.
  • Some services don't have physical locations (e.g., public Wi-Fi)
  • Depending on operator context/capabilities, it is possible have multiple ServiceSites under a single service or multiple services sharing a ServiceSite.
  • Capability discovery does not naturally attach to ServiceSites.

A clean Service abstraction avoids these inconsistencies.

Additional context
This need surfaced during the NetworkAccessDevice and Reboot refactor review, where the team identified several workflows that break down without a Service concept. Additionally, introducing ZTO and client-device onboarding flows increases the importance of unambiguous service context.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions