Migrating from v1 to v2
Version 2 of the Enlighten Systems API was released in May 2014. To upgrade your code to v2, please take into account the following changes.
New Authorization Strategy – API Key and User ID
In v1, a single API key gave a developer authorization to make API requests for all the Enlighten systems to which the owner of that API key had access. In v2, authentication and authorization are managed by two separate credentials: the API key and the user_id.
The API Key
The API key identifies the application that is making the API request. If you are the developer of an application and you have been accumulating the API keys of your application’s users, then you will need to acquire your own API key at this time. Please see the Quick Start Guide for full instructions on how to sign up for an API key.
The user_id
The user_id query parameter on an API request identifies the Enlighten user for whom the API request is being made. A single application may make requests for one or more Enlighten users, identified by their user_ids. For information on how to make a request with a user_id, and for instructions on acquiring user_ids, please see the Quick Start Guide.
Backward-Incompatible Changes in v2
Breaking changes in v2 are listed here. For a full list of non-breaking new features and bugfixes, please see the Release Notes. Enhancements and non-breaking bugfixes are released on a regular basis.
Attributes removed from /api/v2/systems/[id]/summary.
It no longer includes values for energy_week or energy_month. Instead, these ranges and other custom ranges can be calculated from energy_lifetime. Please see the energy_lifetime documentation for more information.
The /api/v2/systems/[id]/stats request does not ‘pad’ the returned array of intervals.
When you request stats for a system, the response includes intervals that have been reported during the requested period. Gaps in reporting — such as before dawn and after dusk — are not filled with 0-value intervals.
The endpoints /api/v2/systems/power_today, power_week, and alerts are removed.
Use the stats request to retrieve power and energy one day at a time for any day up to one year ago.
Note that there is no drop-in replacement for the alerts endpoint: Instead, the “status” attribute returned by the systems request conveys information about what type of troubleshooting, if any, is required on a system. See the systems index request for detailed information about the status attribute.
New information is also provided in the summary endpoint to help with troubleshooting. The “last_report_at” timestamp indicates the last time Enlighten heard from this system. This, in conjunction with the “status” value of “comm” may indicate a communication problem. The “operational_at” timestamp indicates when this system began producing energy, or, in jurisdictions where applicable, when it received permission to operate. This timestamp indicates the earliest time at which to expect production from this system.
Dates and times are treated distinctly.
To simplify date and time formatting, the following changes apply:
- Endpoints that receive and return dates expect the format YYYY-mm-dd, and return them as such. All dates are in the timezone of the requested system. Attributes that are dates are named accordingly; e.g., “summary_date”, “start_date”, “end_date”.
- Endpoints that receive and return times expect the time to be expressed in Unix epoch time, and return it as such.
- Attributes that are times are named accordingly; e.g., “operational_at”, “last_report_at”, “start_at”, “end_at”.
- In some cases, query parameters such as “start” and “end” did not align with the names of the fields in the response. In v2, all start and end parameters are named according to their datatype; e.g., “start_date” instead of “start” for date parameters and “start_at” instead of “start” for time parameters.