How Green Button Made The “Pull-Only” OAuth Standard Support Push APIs Too

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 5

As described earlier, by its nature Green Button data is renewed regularly, typically daily or on a repeatable periodic basis. The new data is made available according to the data custodian’s internal business processes. Thus it is not efficient for a third party to ask for the data whenever it desires it, since the data may not be ready. The obvious answer to consider, as in other such data transfer situations, likely is a PUSH model.

OAuth supports a non-symmetrical protection mechanism for access to authorized resources. The third party must GET resources and offer the access-token as evidence that it is authorized to make the request.

For these reasons, Green Button developed a “pseudo PUSH model.” The model is consistent with the OAuth Resource data exchange model, which is the mechanism by which all Green Button data is exchanged. Specifically, when the data custodian wants to “PUSH” data to the Third Party, it securely sends the third party a Notification POST message. The contents of the Notification is a BatchList, which is a sequence of resource URIs that changed and that the third party is recommended to GET via the normal mechanism. These resource URIs have no PII and are useless without a valid access_token to retrieve data.

This Notification can be used for various purposes:

To notify the third party of newly-available resources to retrieve
To notify the third party of revised scopes and authorization status
To notify the third party of revised parameters of the bi-lateral relationship between data custodian and third party

For example, URIs that a BatchList might include:

the URI for bulk data retrieval indicating the bulk data is ready
the URI for an individual subscription indicating that it has been updated
the URI for an authorization indicating that its status or parameters have changed, such as when a customer terminates the authorization or changes its duration
the URI for the relationship between the data custodian and the third party for a specific resource named “ApplicationInformation”
the URI for an updated specific resource. For example, electricity meter readings are often provided daily as “raw” data and may be corrected at some later time.

Upon receiving the BatchList of resource URIs, the third party looks up the authorization associated with each Resource URL. It uses the access_token in conjunction with the entire resource URL from the BatchList to instruct the GET request to retrieve the data.

This BatchList may include URIs for bulk resources (see below) and/or individual resources.

Bulk Transfer

There’s a lot of data involved, many energy utilities, a huge number of third party providers, and a lot of individual customers. Sometimes that can be daunting. For data to be retrieved daily, the Green Button community needs an efficiency mechanism to enable this transfer.

As a result, Green Button allows the data custodian and the third party to establish one or more “Bulk Transfer” URIs. This mechanism makes use of the Notification method described above. It notifies the third party that data is ready by providing a Bulk Transfer URI in the notification.

The third party can use this Bulk Transfer URI along with a client access token obtained during the third party registration process. The data custodian is responsible for maintaining the list of valid authorizations that may be included in the resulting data set returned by this request. As a result, with a single request, a third party can retrieve a data set of all new and changed resources for which authorization has been previously obtained.