Understanding The Requirements and Standards Behind The Green Button API Initiative

December 9, 2016

MyData API Patterns: OAUTH for Green Button

The article is being updated to reflect the current Function Block values.
Please do not assume accuracy until this message is gone.

Part 2

This article series explains the role of the Green Button initiative, a secure way to communicate energy usage information electronically using standardized RESTful API web services and a common data format. Here we continue with an examination of the architectural underpinnings.

The key requirements for the technology suite used to implement Green Button APIs include:

Do not reinvent the wheel. Use existing standards whenever possible to handle things like security of data in transit, data schemas, token-based Authentication, etc.
Support a diverse set of third party applications, from single user to complex enterprise-wide access. For example, an enterprise use case might be a virtual audit, indicating opportunities for energy efficiency upgrades when a facility is compared to relevant baselines.
Allow for arbitrary complexity of data and data relationships. Unlike “linear” technologies such as comma separated values (CSV) and electronic data interchange (EDI) files, complex data structures permit richer expression of detail and context of data. For example, relationships between measurements and the related tariffs that govern them enable “navigable” data availability beyond just the data in an initial request.
Provide for incremental exploration of available data rather than single batch access. Rich data structures can be potentially large. By allowing data relationships, one data element can be acquired and understood to point to additional levels of detail. This allows a client to navigate to the data of interest rather than have to retrieve anything and everything and sift through what is wanted. This is especially beneficial for small devices that don’t have or want to support large data buffers to sift through unneeded information.
Protect data privacy, allowing for anonymous data and aggregation. Many applications of data about individuals do not need the individual identity to be useful. For example, a store kiosk might make recommendations based on anonymous data. Data fusion often involves “rolling up” contributing data into aggregated digests that present useful summaries.
Implement a high degree of security in machine-to-machine web services. Modern communications must protect the confidentiality, integrity, and availability of data on demand.
Enable specification of which data (held by the data custodians) is available to third parties at a granular level. Not every third-party service provider needs or should have access to all data for a retail customer. Enabling granular access provides maximal control of data by individuals and organizations.
Permit large populations of authorizations to have data retrieved by a third party in bulk. Large third-party service providers may obtain the right to access data on large numbers of customers of a data custodian. Exclusively requiring individual access is inefficient and consumes both time and bandwidth.
Implement data identification and life cycle management. Data is not static. Often it needs to be updated or enhanced with new information. Recognizing versions of the same data set and which is the “latest” is essential to managing its proper interpretation.

The Green Button technology is based on well-established existing standards that were assembled to meet the identified requirements. These requirements are presented in the subsequent sections that summarize them and elaborate their resolution. This series deals specifically with requirements for establishing third party authorization.

The following table summarizes the key standards used:

Standard	Purpose	Usage
IEC 61968-9 2^nd Edition Application Integration at electric utilities - System interfaces for distribution management - Part 9: Interfaces for meter reading and control	Information Model	Core information model for Green Button Energy Usage Information
NAESB REQ.21 Energy Services Provider Interface (ESPI)	Use Cases and APIs	Profile of the IEC standard used for Green Button and which elaborates the basic API use cases. (Note: the certified Green Button applications are based on extensions to the NAESB standard and not the standard alone.)
RFC 4287 Atom Syndication Format (atom.xsd)	Data Serialization	Syntactical representation of data in XML including information metadata
RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace	Data Identification	Globally unique identifiers used to identify data transferred
RFC 6749 The OAuth 2.0 Authorization Framework	Third Party Authorization	Authorization of data to Third Party service provider
RFC 6750 The OAuth 2.0 Authorization Framework: Bearer Token Usage	Third Party Authorization	How to use bearer tokens to govern authorized messaging
RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (now v1.3)	Message Authentication	Secure messaging over TCP/IP
RFC 2818 HTTP Over TLS	Secure Messaging	Use of HTTPS for secure API messaging
RFC 3986 Uniform Resource Identifier (URI): Generic Syntax	REST Path Syntax	Format of REST URIs
espi.xsd Reference Schema	Schema for Green Button usage data	Used to describe Green Button usage-data structures
customer.xsd Reference Schema	Schema for Green Button retail-customer information	Used to describe Green Button retail-customer data structures

Those are the standards upon which we built. In the next article, OAuth and Green Button, we describe the building blocks and how they respond to the project requirements.