API endpoints for automation and integration

[kohlerdominik]

Describe the problem you are trying to solve

We are trying to interact with SteVe with a third party service in a micro service architecture. SteVe should manage the charging points, but we need to extract consumed energy information.

Describe the solution you'd like

If SteVe would provide API-endpoints for relevant information, Machine-to-Machine communication and therefore automation and integration in other systems would be possible.

Three important use cases came to our mind:

• connecting SteVe with smart devices, making automation possible. For examples see ifttt.com
• integration of SteVe in a micro service architecture
• create a solid base for a possible frontend modernization, probably a Single Page Application

Additional context

This feature request was discussed between @goekay and @lextira in a video call, and it was agreed to cover two key features for now:

• create, read, update, delete of RFID-Tokens from a third party service (key feature for authorization automation)
• read transactions (key feature for reporting automation)

[goekay]

ToDos:

• [x] REST Controller for OCPP Tags with CRUD functionality (i.e. what OCPP Tags page under Data Management offers: same querying possibilities, same response data models). JSON payloads.
• [x] REST Controller to read transaction info (i.e. what Transactions page under Data Management offers: same querying possibilities, same response data model). JSON payloads.
• [x] Swagger (i.e. OpenAPI 3) documentation for the endpoints.
• [x] Authentication for these endpoints via a static API key that will be specified in main.properties

[anirudh-ramesh]

Hi @goekay, can you please suggest how to contribute to this feature request? I had made an OpenAPI specification for an HTTP REST API and began implementing it through an API controller, but that is WIP and nowhere near completion. However, I had completed adding Swagger UI to SteVe. I would be glad to contribute a few snippets if that is suitable for you.

[anirudh-ramesh]

The endpoints that had been implemented and manually tested are as follows:

• Read charger properties (filter for active)
• Read tag properties
• Read transaction properties (filter for ongoing transactions)
• Start a transaction i.e. create a task to start a transaction
• Read last intermediate energy meter value and electricity consumed (kWh or Wh depending on the charger)
• Stop a transaction i.e. create a task to stop a transaction

[goekay]

hey @anirudh-ramesh, thanks for your work! this feature request and its realisation has a very clear scope, and therefore i would like to keep it that way. while working on this, i am also laying some ground work (such as auth and openapi spec) for further extensions.

if you'd like, you are welcome to make a PR (after this is finished and merged) of your impl where your endpoints use the ground work introduced by this one. thanks!

[frmunozForcast]

Hi @goekay, great work here, I'm very interested in this feature request. How long do you think it will take to complete it for an usable scenario?. Thanks.

[goekay]

@frmunozForcast it is usable already ;)

[iprastha]

Hi, is this feature already released or under a specific branch? Thank you!

[goekay]

hey @iprastha there is no release yet, but you can see the referenced commits above in the respective feature branch.

[cbrandlehner]

@goekay am I right, that the next step is to create a pull request so that the commits can be merged and released?

[goekay]

yes, that is correct. i am waiting for the testing by and feedback from @kohlerdominik to make a PR and merge it. as far as can see, the feature impl is complete.

[kohlerdominik]

Hi all

Sorry for my delay. Just this week I started testing and implementation on our end. I think there are some minor things I want to give as feedback to @goekay, so he can consider wether he want's to adjust them, and after that we're good to go. I will finish feedback until the end of the week.

However, by simply checking out the branch 910-api-endpoints-for-automation-and-integration, everyone can already use it.

[cbrandlehner]

@kohlerdominik I tried to but found no documentation on the new APIs. All I found was a configuration option for the API key and token.

[goekay]

true, that's an area for improvement. i try to write useful commit messages though. you can see that, if you checkout the branch and start steve, the endpoint /manager/v3/api-docs will show you the API spec.

[goekay]

Hey everyone, this feature is merged and part of master branch.

Thanks to @enertech-ch for sponsoring the feature, and to @kohlerdominik for the collaboration!

[juherr]

This feature is awesome and open a lot of new options. Well done 👍

[goekay]

@kohlerdominik I tried to but found no documentation on the new APIs. All I found was a configuration option for the API key and token.

@cbrandlehner i added a section about this. is it good enough for you to get started? the majority of the integration work should come from inspecting open-api spec and its capabilities. the documentation is the spec.