Announcements

December 1st 2021

Greetings from EnerKey API dev team!

Hi!

EnerKey API has been under a lot of improvements for a while. We have changed the way we let our customers to interact with our APIs. Instead of directly connecting to backend, we have now utilized an API Gateway platform which handles the authentication and proxies our customers requests to correct backend. Hooray!

It has been quite a rollercoaster to figure out best approaches but thanks to your patience and feedback, we have now formed working setup.

Although, there were some sacrifices to be made since our approach at some areas was not perfect by design. In the old way we accepted unencrypted HTTP-requests but from now on HTTPS is forced. There were also some endpoints where we did not have standards good enough and they have been replaced. They mostly differ from the way you provide arrays of information. In the old way they were provided in route or as query params. That resulted in broken API Definition YAMLs and JSONs and could cause crashing in some code generators.

For those kind of endpoints we have implemented more type safe equivalents where arrays are provided in body and GET-method usage is replaced with POST. Changes affect following endpoints:

  • GET /api/v1/Actions/

  • GET /api/v1/Images/consumptionreport/

  • GET /api/v1/Meters

  • GET /api/v1/Quantities

  • GET /api/v1/Facilities

  • GET /api/v1/Values/hourly/

  • GET /api/v1/Values/monthly/

  • GET /api/v1/Values/normalized/

Those endpoints are to be replaced with v2 -equivalents using POST. Documentation for those can be found here. Hit "Show URL path" -switch to be able to quickly find correct endpoint by route. We highly encourage to start using new endpoints instead of the old ones since we plan to deprecate those endpoints and stop supporting them after June 2022. So if you are currently using these deprecated endpoints, please start using their v2 equivalents ASAP.

Provisioning

Other replacements are also planned to be done. EnerKey API has included Provisioning endpoints as embedded resources (found here, hit "Group by tag" and browse to Provisioning tagged operations). In the future we want our provisioning customers to use separate Provisioning API (found here). Moving there removes additional layering and provides us better ways to troubleshoot possible problems. Also automatically generated documentation stays in better shape for serving you in best possible ways. The changes you need to do is change baseurl suffix and some operation names are different. Not a big task, since DTOs are basically identical.

Changelog

We always look forward to exceed expectations. Modification needs for our APIs are constant and sometimes new content is added without our customers knowing about it.

Next to "API definition"-dropbox at API details is a Changelog link where we give you a brief explanation what is happening within our releases considering the API you use. Keep a close look on that one since we have big plans to provide better control to your data in EG EnerKey SaaS.

Summary

So long story short, we kindly expect our API customers to perform following:

  • Start using HTTPS instead of HTTP

  • If you are using deprecated endpoints described earlier in this post, please move to their v2 equivalents ASAP

  • If you are using Provisioning, please move to separate Provisioning API