How Green Button Made The “Pull-Only” OAuth Standard Support Push APIs Too
MyData API Patterns: OAUTH for Green Button
Please do not assume accuracy until this message is gone.
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 “
- 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.
BatchList may include URIs for bulk resources (see below) and/or individual resources.
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.
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?