Understanding the Green Button API Initiative and Why It Matters

MyData API Patterns: OAUTH for Green Button

In this Series

• Intro: Understanding the Green Button API Initiative and Why It Matters
• Part 1: Getting To Know The Primary Use Cases of The Green Button API initiative
• Part 2: Understanding The Requirements and Standards Behind The Green Button API Initiative
• Part 3: How Green Button Ingeniously Extended The OAuth Standard Without Forking It
• Part 4: How The Green Button API Initiative Takes Advantage of OAuth's Scope Parameter
• Part 5: How Green Button Made The "Pull-Only" OAuth Standard Support Push APIs Too
• Conclusion: How Can Other API Implementations Benefit From Green Button's OAuth Inventions?

Intro

The My Data initiatives are part of the Obama Administration’s efforts to empower Americans with secure access to their own personal data, and to increase citizens’ access to private-sector data-based applications and services. With its focus on personal data, the My Data initiatives complement the administration’s broader set of Open Data initiatives, which are making government data and other resources more open and accessible to innovators and the public. Together, these initiatives are creating a more comprehensive data ecosystem in which citizens can receive services based on analysis of their own personal data in the context of greater information and understanding of overall trends.

For example, in 2010, the Department of Veterans Affairs created Blue Button to give patients access to their own health records. The Blue Button ecosystem has grown to include many health providers and health plans, enabling more than 88 million Americans to have digital access to their own health records. Other efforts in the Departments of Energy, Commerce, Education and other Federal entities are helping citizens access their own information as fuel for more informed, effective decision making.

Another in the My Data initiatives is Green Button, a secure way to communicate energy usage information electronically using standardized RESTful API Web services and a common data format.

This series of articles discusses the Green Button initiative and how it uses OAuth 2.0 to perform third-party authorization and access. We cover:

• Defining Green Button (this article)
• Understanding Green Button’s Technical Elements
• Using OAuth and Green Button
• Working with Green Button’s Scope

Developers who are familiar with OAuth should expect the following terminology, used differently in Green Button circles but with easy equivalents to OAuth terms. The following summarizes these key terms:

What is Green Button?

The vision for the Green Button initiative was first announced in September 2011, through the U.S. Chief Technology Officer’s “call to action” to the electricity industry to create a “Green Button” to enable consumers to download their own energy usage information from their utilities’ secure websites in a standardized electronic format.

The goal of the Green Button initiative is to increase consumers’ access to their own energy usage information data, supported by an ecosystem of Green Button standards, testing and certification, developer support tools, applications and services. With voluntary adoption by many utilities nationwide, by 2016, over 60 million U.S. customers (representing over 100 million citizens) and over 2.5 million Canadian customers (representing over 8 million Canadian citizens) had Green Button data access.  Mandates for Green Button over the last several years have dramatically increased those numbers. 

Many organizations and stakeholders have supported the development of Green Button, including the White House Office of Science and Technology Policy (OSTP), the National Institute of Standards and Technology (NIST), the Department of Energy (DOE), and private sector organizations which include the UCA International Users Group (UCAIug), the Smart Grid Interoperability Panel (SGIP), the North American Energy Standards Board (NAESB), utilities, industry vendors, and application developers. With this broad support, the Green Button initiative has created a growing energy usage information ecosystem over the past few years, including the establishment of the Green Button Alliance (GBA) in 2015—a private sector nonprofit trade organization dedicated to supporting Green Button. The GBA plays a similar role for Green Button as does that of the Wi-Fi Alliance in establishing branding, testing, and certification for implementations of IEEE 802.11x for wireless Ethernet.

In the following articles, we describe the current state of Green Button technology, including contributions by NIST and its partners. Different stakeholders have contributed to this body of work throughout its development. Building on standards requirements contributed by the Open Automated Data Exchange Task Force (previously a working group under UCAIug and now led by the GBA), NIST and the SGIP initiated a priority action plan to accelerate standards development and implementation. NIST hosted an innovative information modeling “tiger team” which pulled contributions from leading standards efforts on energy usage information (EUI) to develop a key initial core UML modeling contribution. This in turn enabled subsequent development of the essential Green Button technical standards in NAESB, a standards development organization accredited by the American National Standards Institute (ANSI).

Plenty has been accomplished so far. The federal government has been a key driver of this work, working collaboratively with industry. NIST and DOE supported the U.S. CTO in key first adopter discussions and providing technical guidance. They achieved broad agreement on a standards-based XML electronic format that enabled California utilities to complete pilot implementations in less than four months. DOE supported an “Apps for Energy Challenge” focused on Green Button to kick start application development to help engage consumers. NIST and others, including Energy Open Source (EnergyOS), developed open-source / API Reference implementations, testing tools, and technical materials, which support the creation of a comprehensive Green Button ecosystem that empowers consumers and entrepreneurs alike.

In creating Green Button technology, numerous innovative approaches have been developed, building on existing best practices for Web services development, including Atom syndication format to provide metadata and OAuth 2.0 for third-party authorization. These advances enable Green Button to serve as a useful “pattern” for other data initiatives facing similar challenges. The novel extensions to OAuth that were derived from the requirements of the Green Button use cases are described in detail in this series.

Next in this Series

• Intro: Understanding the Green Button API Initiative and Why It Matters
• Part 1: Getting To Know The Primary Use Cases of The Green Button API initiative
• Part 2: Understanding The Requirements and Standards Behind The Green Button API Initiative
• Part 3: How Green Button Ingeniously Extended The OAuth Standard Without Forking It
• Part 4: How The Green Button API Initiative Takes Advantage of OAuth's Scope Parameter
• Part 5: How Green Button Made The "Pull-Only" OAuth Standard Support Push APIs Too
• Conclusion: How Can Other API Implementations Benefit From Green Button's OAuth Inventions?