Skip to content

DC: serve Batch/Subscription/{id} (the customer token's resourceURI) as one subscription-scoped Atom feed #279

Open

Description

@dfcoffin

Problem

A customer access token's resourceURI is {DC}/espi/1_1/resource/Batch/Subscription/{subscriptionId}, which the AS returns per REQ.21 6.1.2 and the DC's back-channel provisions. The DC does not serve that URI (CLAUDE.md lists Batch/Subscription as not implemented), so a Third Party cannot retrieve the customer's data with the URI it was given.

The DC's Subscription/{subscriptionId}/UsagePoint… GETs exist, but they ignore subscriptionId and return every customer's records (the #187 known defect). There is also no MeterReading or ReadingType list under a subscription.

Needed for the last Phase 1 exit criterion of #255, "the TP displays that customer's usage data". Decided while starting #197: the TP fetches exactly its resourceURI. This is the second of three PRs: #197 → this → minimal #89.

Scope

GET {DC}/espi/1_1/resource/Batch/Subscription/{subscriptionId} returns one Atom <feed> holding that subscription's energy usage data.

Contents:

  • the subscription's UsagePoints (SubscriptionEntity.usagePoints, the ones the customer selected on the Authorization Screen);
  • for each UsagePoint: its LocalTimeParameters / TimeConfiguration, MeterReadings, ReadingTypes, IntervalBlocks, UsageSummaries and ElectricPowerQualitySummaries;
  • only the Function Blocks the token's scope grants (for example, no UsageSummary without FB_16).

Format:

Access:

  • Customer access tokens only: an authorization_code token whose introspected resourceURI names this subscription.
  • The subscription id in the path must equal the token's. Anything else gets 403, with no hint of whether the subscription exists.
  • The DC admin token (DataCustodian_Admin_Access) may read any subscription.
  • The client access token (FB=34_35) is refused; it is for Bulk (DC: implement ESPI Batch/Bulk API — Third Party client access token only, scoped to its own Authorizations #256) and Authorization.
  • The rule lives in ScopeResolver, which already maps Batch/Subscription/{id} to the subscription's UsagePoint ids from the DC's own store; no separate rules per controller.

Not in scope: Batch/Bulk (#256), Batch/RetailCustomer (the customerResourceURI), notifications.

Implementation notes

Tests

  • A customer token for subscription A gets exactly A's UsagePoints and children. Subscription B's data is absent, even when it lives at the same DC.
  • A token for A requesting B gets 403. The client access token gets 403. The admin token gets 200.
  • A scope without FB_16 gets no UsageSummary entries.
  • An empty subscription returns a valid empty <feed>.
  • The response validates against atom.xsd + espi.xsd (apart from the ESPI DTO enums are written as Java constant names, not the XSD values (e.g. ServiceCategory) #278 items).

Related: #187, #197, #89, #255, #256, #278.

Activity

  1. dfcoffin commented on Nov 18, 2026

    @dfcoffin
    ContributorAuthor

    Note from the #280 review: when BaseExportService.buildFeed gets an empty list, it takes the feed's self-link type (espi-feed/{resource}) from the last path segment of feedHref, because there is no entry to name the resource. Every current caller's href ends in the resource name, so the guess is right today.

    Batch/Subscription/{subscriptionId} ends in an id. An empty subscription would therefore get type="espi-feed/{id}". The result still passes atom.xsd, but the ESPI link type is wrong.

    When this endpoint is added, pass the feed's resource name to buildFeed explicitly rather than inferring it from the URL, and add a test for an empty Batch/Subscription feed.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions