Repository navigation
Description
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:
- Each resource in its own
<entry>, inside<content>(Third Party cannot unmarshal any ESPI Atom feed (AtomFeedDto date adapters + abstract entry type) #197), with self/up/related links. - Entry order as in certified feeds: UsagePoint, then its children.
- IntervalBlocks limited by the scope's
HistoryLength/BlockDurationwhere those terms are present.
Access:
- Customer access tokens only: an authorization_code token whose introspected
resourceURInames 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 mapsBatch/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
- Build the feed from
SubscriptionRepository.findUsagePointIdsBySubscriptionIdand the existing DTO mappers /DtoExportService. If E1: DC resource engine + Atom entry-assembly (GET-first) — UsagePoint & Customer verticals, scope-enforced #187 has merged by then, build it on the E1 resource engine. - Use
EspiBatchUrifor parsing and building the URI (the single source of truth, AS↔DC token/introspection wire format diverges from ESPI standard (Batch URI forms + non-standard *_id claims) #160). - XSD-validate the response in tests (the Third Party cannot unmarshal any ESPI Atom feed (AtomFeedDto date adapters + abstract entry type) #197 schema validator). Known failures from ESPI DTO enums are written as Java constant names, not the XSD values (e.g. ServiceCategory) #278 (enum values) are tracked there and must not block this.
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).
Activity
dfcoffin commentedon Nov 18, 2026
Note from the #280 review: when
BaseExportService.buildFeedgets an empty list, it takes the feed's self-link type (espi-feed/{resource}) from the last path segment offeedHref, 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 gettype="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
buildFeedexplicitly rather than inferring it from the URL, and add a test for an emptyBatch/Subscriptionfeed.fix(datacustodian): apply HistoryLength to summaries in Batch/Subscri…
fix(datacustodian): Batch/Subscription query range, HistoryLength cei…
feat(datacustodian): Batch/Subscription UsagePoints by commodity Func…
fix(datacustodian): Batch/Subscription requires FB_4 plus an electric…
fix(datacustodian): HistoryLength in months, second #282 review fixes (…
fix(datacustodian): HistoryLength from every usage-data scope, not on…
fix(datacustodian): HistoryLength back to seconds, per REQ.21.6.1.2.1 (…
fix(datacustodian): third #282 review fixes (#279)