This is part 2 of our series What is The Green Button API initiative and How It Took OAuth To An Entirely New Level. Part 1 of the series introduced the Green Button’s goals and use cases.
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:
|IEC 61968-9 2nd 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||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||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|
|espiderived.xsd Reference Schema||Schema for Green Button data||Used to describe all Green Button data structures|
That’s the standards upon which we built. In the next article, OAuth and Green Button, we describe its building blocks and how they respond to the project requirements.
This is part 2 of our series What is The Green Button API initiative and How It Took OAuth To An Entirely New Level. In part 3, we'll describe the building blocks of Green Button technology with respect to authorization of access to data provided to third parties. This series was co-authored by Dr. David Wollman, Deputy Director, Smart Grid and Cyber-Physical Systems Program Office, National Institute of Standards and Technology.