Data for Discussion on Atom Links in ESPI

Data for Discussion on Atom links in ESPI

4/9/2018 13:18:40 a4/p4

1 Problem Statement We need a definitive profile for what links to put in a Green Button dataset and how to form the URIs. We have two help desk issues 58&72 on this subject. Additionally, the issue of how to handle a single request covered by multiple authorizations needs addressing: [58] Guidelines are needed for proper usage of hrefs in the Atom representation 2 [72] Remark about test # FDFTP6 (related links matching self links) I believe a key uncertainty is when to have a link point to a collection and when to point to an instance. Additionally there is the advisability of including uplinks. A concrete set of guidelines would be a good outcome of the discussion with a sensitivity to how choices impact interoperability of applications. The results might show up as an addition to the standard clarifying the subject, and/or, tests in the conformance test suite.

2 What the Standard (REQ21) Says The following addressable objects (specializations of IdentifiedObject) are defined by the ESPI schema, and can be made available using AtomPub feeds.  UsagePoint  ReadingType  IntervalBlock  MeterReading  Subscription  ElectricPowerUsageSummary  ElectricPowerQualitySummary  Authorization  ApplicationInformation  Recommend adding per HDI#62: LocalTimeParameters

Links shall use the following tags and values to convey link types.

Association rel type UsagePoint  MeterReading related application/atom+xml UsagePoint  ElectricPowerQualitySummary related application/atom+xml UsagePoint  ElectricPowerUsageSummary related application/atom+xml MeterReading  IntervalBlock related application/atom+xml MeterReading  ReadingType related application/atom+xml

URIs are kept as short as possible, and do not exceed 255 bytes. Relative URIs may be used when resources are on the same host. Additional definition regarding URIs and HTTP/S follow the IETF specifications. A URI example is provided below.  https://espi.datacustodian.com/{third_party_id}/Batch Since all URIs are opaque references, there is no mandated form. However, it may be useful to organize them hierarchically, in order to define URIs for the appropriate containers (feeds), and to manage permissions. URIs should be as persistent as possible, but they may change. atom:id, however, does not change, even if the resource is moved or replicated. Clients accessing out-of- date URIs may be redirected, but if they are not, may need to request the current preferred resource location. The following query parameters are used to filter the resources returned by a feed. These use typical “?name=value[&…]” syntax.  published-max, published-min  updated-max, updated-min  max-results  start-index

Date and time values for the above parameters use RFC 3339 format.

3 Atom Links and ESPI This section illustrates the linking issue. First is presented a diagram showing the rough correspondence between the components of an Atom Feed and those of the Green Button (ESPI) object model. Second is an illustration showing how recommended linking works. 3.1 Composition and Atom Feeds

Figure 1: Correspondence Between ESPI Objects and Atom Entrys 3.2 ESPI Linking Atom Entry = Resource that is an identifiedObject in ESPI Atom Feed = Resource that is a Collection of identifiedObjects Figure 2: Use of Links in Atom for ESPI

3.2.1 Sample XSLT navigation Based on the figure, if links are implemented according to this scheme, then the links may be navigated with XPath statements as illustrated in the following XSLT templates.

3.2.1.1 Following a related link

3.2.1.2 Following an up link

4 Proposed Link Best Practices This is the proposed end result of the exercise – that is, a set of best practices for populating the link attributes of Atom Entrys. 1. Every entry shall have an uplink to its parent feeds. 2. URLs are opaque and not designed to be parsed for navigation. They may reflect the internal storage or layout of the servers which will vary. Therefore clients should not make any assumptions about their structure. 3. If a server supports retrieving feeds, the feeds shall have an uplink to its parent entry. 4. When the multiplicity in the data model is not 1:1, the “related” link must point to a feed 5. When the multiplicity in the data model is 1:1, the “related” link must point to an entry 6. Batch defines the set of atom entrys that pertain to a common single Authorized resource. 7. Bulk defines a set of atom entrys that pertain to multiple authorized resources theoretically with separate individual or Batch authorizations. 8. A Subscription pertains to any single resource. However, Subscription is probably always a feed. 9. Use of BatchItemInfo. If you want to support multiple requests (e.g. http requests) in a single call, you would need BatchItemInfo to distinguish the results. This probably needs to be elaborated further in the standard. *** should result in a new Help desk item 10. All collections of atom entrys are returned as a feed. 11. entry/@base or feed/@base may have a common URL base after which all relative link URIs are appended. e.g. feed/@base = http://my.web.com/DataCustodian/. If there is a conflict between base and a resource link, use the resource link. 4.1 Details of Sample links Note URLs are opaque and should not be assumed to have any clear structure. However, some organization may be beneficial to the Data Custodian implementing them as a hint when viewing raw XML. The samples here are provided to show one possible organization. These URLs have the pattern [[tag]/[id]/]*. Collections are always implied to exist at the tag boundaries. Whether these collection points are useful or not remains to be seen. The IDs should be obfuscated (random) when the ID represents an entity or user, incremental integers for others. However, these patterns are suggested and convenient but not required or tested for.

The batch feed: ThirdParty/10002/Batch ^ +------Obfuscated Unique ID for to identify a specific 3rd party we are interacting with, each 3rd party has a unique id in our system. The UsagePoints: RetailCustomer/4299914/UsagePoint/4284792 ^ ^ | +- Obfuscated Unique ID for a customer’s premise and usage point (typically service point) id at a specific 3rd party +------Obfuscated Unique ID for a customer at a specific 3rd party

MeterReadings:

First MeterReading of a UsagePoint: RetailCustomer/{retailCustomerID}/UsagePoint/{usagepointID} /MeterReading/1 ^ +------MeterReadingID

Second MeterReading of a UsagePoint: RetailCustomer/{retailCustomerID}/UsagePoint/{usagepointID} /MeterReading/2

ReadingType: ReadingType/02 ^ +------Represents a single “signature” reading type global for the portal. One for each specific measurement and its metadata.

IntervalBlock: RetailCustomer/{retailCustomerID}/UsagePoint/{usagepointID} /MeterReading/{meterReadingID} /IntervalBlock/{blockID} ^ +------Represents block ID sequential number unique to date-time interval 4.2 Links provided in SDK Sample files This section shows the links that are in the Green Button SDK sample files (modified according to the “best practices” scheme.

4.2.1 Feed

4.2.2 UsagePoint

4.2.3 MeterReading

4.2.4 ReadingType

4.2.5 IntervalBlock

4.2.6 ElectricPowerUsageSummary 4.3 Future Work

Future concept for standard: The “rel” link should have a value based on the schema http://naesb.org/espi /UsagePoint. Also for the “up” links. Notes from Heiko: Future concept for standard: The “rel” link should have a value based on the schema http://naesb.org/espi/UsagePoint. Also for the “up” links.

The navigation concept expressed in my graphic and XSLT fragment can be adapted to such an improved link schema, provided that the rel values that replace rel="related" (e.g., http://naesb.org/espi/MeterReading) can be distinguished from the rel values that replace rel="up".

For example, the "up values" might be http://naesb.org/espi/MeterReading/up, then the application could check whether they end in "/up" (hence they would not be opaque).

Or, more elegantly, following http://www.w3.org/TR/html401/struct/links.html#h-12.3.1, the related-links could be regarded as forward links and the up-links as reverse links, then we would have for the related-link and for the up-link. But I am afraid that rev is not used by Atom.