Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

@andig
Copy link
Member

@andig andig commented Jul 10, 2025

Simplify HTTP JSON response format. Remove "result": {} wrapper.

Example GET /api/state

before

{
  "result": {
    "loadpoints": [...],
    ...
  }
}

after

{
  "loadpoints": [...],
  ...
}

TODO

@andig andig requested a review from naltatis July 10, 2025 19:42
@andig andig added infrastructure Basic functionality needs documentation Triggers issue creation in evcc-io/docs labels Jul 10, 2025
@andig andig marked this pull request as draft July 10, 2025 19:43
Copy link
Contributor

@sourcery-ai sourcery-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @andig - I've reviewed your changes - here's some feedback:

  • This change breaks client contracts by removing the result wrapper, so please bump the API version or add a migration note to alert consumers of the new response format.
  • Make sure you update and regenerate the OpenAPI spec (and any MCP artifacts) before merging so the docs match the new JSON responses.
  • Double-check that all downstream code (including website components and integrations) has been updated to use response.data instead of response.data.result.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- This change breaks client contracts by removing the `result` wrapper, so please bump the API version or add a migration note to alert consumers of the new response format.
- Make sure you update and regenerate the OpenAPI spec (and any MCP artifacts) before merging so the docs match the new JSON responses.
- Double-check that all downstream code (including website components and integrations) has been updated to use `response.data` instead of `response.data.result`.

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

@andig
Copy link
Member Author

andig commented Jul 10, 2025

Make sure you update and regenerate the OpenAPI spec (and any MCP artifacts) before merging so the docs match the new JSON responses.

Schlaubi ;)

@andig
Copy link
Member Author

andig commented Jul 10, 2025

@naltatis integration hab ich wohl verdaddelt- dass das dann 17 Minuten läuft ist aber auch nicht schön?

@naltatis naltatis changed the title API: simplify json response by removing `result wrapper API: simplify json response by removing result wrapper (BC) Jul 10, 2025
@naltatis
Copy link
Member

dass das dann 17 Minuten läuft ist aber auch nicht schön?

ich schau mir die Timeouts mal an.

@StefanSchoof
Copy link
Contributor

@TheNinth7 Ich denke dieser PR wird für deine Garmin App Breaking.

@andig
Copy link
Member Author

andig commented Jul 11, 2025

No hurry, lets see if we can get this working first and then prepare transition.

@TheNinth7
Copy link

@TheNinth7 Ich denke dieser PR wird für deine Garmin App Breaking.

Ja, Danke für den Hinweis, werde die App entsprechend vorbereiten!

@naltatis naltatis changed the title API: simplify json response by removing result wrapper (BC) REST API: simplify json response by removing result wrapper (BC) Jul 11, 2025
@marq24
Copy link
Contributor

marq24 commented Jul 11, 2025

... currently the existence of a result object (in json response) is a true indication (in the ha-evcc), that there had been no other issues/errors with the request/response...

So when this result container object will be removed, at least the possible error evaluation & handling will become more complex...

@Maschga
Copy link
Collaborator

Maschga commented Jul 11, 2025

currently the existence of a result object (in json response) is a true indication (in the ha-evcc), that there had been no other issues/errors with the request/response

How about checking whether the status code is 200?

@andig
Copy link
Member Author

andig commented Jul 11, 2025

Exactly that 👍🏻

@marq24
Copy link
Contributor

marq24 commented Jul 11, 2025

How about checking whether the status code is 200?

of course the ha-integration is checking for http status 200, before reading any json data... I personally prefer, when http status codes are not used to indicate application layer information - so http 200 must not mean, that the response itself have valid/consistent data... But since this is just my opinion, and since it's your project, I will adopt to this change.

@andig
Copy link
Member Author

andig commented Jul 11, 2025

I'm not saying that it necessarily does but at the same time I'm not aware of any best practice requiring wrapping json payloads in top level elements which is what we're changing here.

and since it's your project,

I disagree (and I personally don't like the wording). It is a community project and we're open to feedback! Adhering to best practices certainly is of high value to us.

@marq24
Copy link
Contributor

marq24 commented Jul 11, 2025

I disagree (and I personally don't like the wording). It is a community project and we're open to feedback! Adhering to best practices certainly is of high value to us.

I must assume, before starting with this breaking 'everything' change, you had internally (e.g. in slack) discussed the pro's & con's already. I highly appreciate the overall structure of this project and the clean code principles. So there is great experience & expertise in the core development group. Getting rid of an obsolete container object seams to be reasonable.

The only thing I wanted to remark was triggert by "why not (simply) check for http 200?" - From my point of view, http 200 should not be the indicator, that the response object is in the expected format or structure. So processing any API response with http status 200 must be done with care and without any additional assumptions.

In the HA integration, I have (mis)used the presence of the result container in any of the API responses, as validation: that the request was processed by an evcc-endpoint and "seams to be valid in it's internal structure" - at least it has not been generated by any infrastructure in between. For sure this approach was also far from being perfect, but IMHO it is quite a cheap' approach (CPU & data wise) and nobody really want to return to SOAP.

So when the result will not be present any longer, I have to rethink the current data-validation-procedure - which probably take less time, then writing this reply :-)

marq24 pushed a commit to marq24/ha-evcc that referenced this pull request Jul 11, 2025
- re-configuration instead of options
- prepare for "result" container being removed (evcc-io/evcc#22299)
marq24 pushed a commit to marq24/ha-evcc that referenced this pull request Jul 11, 2025
- re-configuration instead of options
- prepare for "result" container being removed (evcc-io/evcc#22299)
@marq24
Copy link
Contributor

marq24 commented Jul 11, 2025

@TheNinth7
Copy link

TheNinth7 commented Jul 12, 2025

An update for the Garmin app will be released in the next few days, adding support for both JSON formats - with and without the "result" wrapper. The app uses a jq filter to reduce memory usage, and the filter has been updated to handle both cases.

The code was tested with the old format, but I can only fully verify support for the new one once the update is live. Mock servers can't replicate how the jq filter is applied by the actual server.

Side note: AI isn’t much help with Garmin’s Monkey C or SDK, but it is well-versed in jq and was also helpful in this case. 😉

@TheNinth7
Copy link

@andig I also noticed the openHAB evcc binding isn’t showing up in the list. Maybe it needs an update too to handle the new JSON format?

@andig
Copy link
Member Author

andig commented Jul 12, 2025

Whom do we need to cc?

@TheNinth7
Copy link

Whom do we need to cc?

@florian-h05, would you be the right person to look into how this change affects the openHAB evcc binding? Or do you happen to know who maintains it currently?

marq24 pushed a commit to marq24/ha-evcc that referenced this pull request Jul 14, 2025
- prepare for "result" container being removed (evcc-io/evcc#22299) - fix
- initial handling of chargerSinglePhase, chargerFeatureIntegratedDevice loadpoint attributes
- do not add (vehicle) entities for loadpoints that are 'IntegratedDevice'
arteck added a commit to Newan/ioBroker.evcc that referenced this pull request Jul 16, 2025
* (arteck) simplify json response by removing result wrapper, see evcc-io/evcc#22299
@andig
Copy link
Member Author

andig commented Jul 17, 2025

Announcement is done via release notes and discussions: #22416.

I'd tentatively like to schedule this for 0.206.0.

@marq24
Copy link
Contributor

marq24 commented Jul 17, 2025

I'd tentatively like to schedule this for 0.206.0.

my experience with HA Integration users is, that they update Integrations not frequently - but the obvious question is, "how long you are willing to wait" with the rollout of this PR... In my opinion this change does not add any (awaited) functionality - therefor the release-pressure is not high (IMHO)

@andig
Copy link
Member Author

andig commented Jul 17, 2025

The pressure comes from the other release contents. But we'll need to merge this into the nightly before.

that they update Integrations not frequently

This will be an issue for any release, be it sooner or later?

@capi
Copy link

capi commented Jul 17, 2025

Maybe make it a "dedicated" release, where people can roll-back to the previous version if they cannot immediately update their integrations? I guess, a lot of people are on the "latest" tag when using Docker and will otherwise be quite surprised by the update and it would be beneficial, if they could rollback one version in order to update their home automation integrations.

@github-actions github-actions bot added the stale Outdated and ready to close label Jul 24, 2025
@naltatis naltatis removed the stale Outdated and ready to close label Jul 28, 2025
ohAnd added a commit to ohAnd/EOS_connect that referenced this pull request Jul 30, 2025
@andig andig marked this pull request as ready for review August 1, 2025 12:49
Copy link
Contributor

@sourcery-ai sourcery-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @andig - I've reviewed your changes - here's some feedback:

  • Please regenerate and commit the updated server/mcp/openapi.json so the OpenAPI schema matches the new top-level response structure.
  • Add a clear migration note or section for API consumers about this backward-incompatible removal of the “result” wrapper.
  • Double-check that all frontend service calls and components have been updated to use response.data instead of response.data.result with no leftover .result references.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- Please regenerate and commit the updated server/mcp/openapi.json so the OpenAPI schema matches the new top-level response structure.
- Add a clear migration note or section for API consumers about this backward-incompatible removal of the “result” wrapper.
- Double-check that all frontend service calls and components have been updated to use response.data instead of response.data.result with no leftover .result references.

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

@andig andig enabled auto-merge (squash) August 1, 2025 12:58
@andig andig merged commit d541dfa into master Aug 1, 2025
6 checks passed
@andig andig deleted the feat/api-structure branch August 1, 2025 13:00
@andig
Copy link
Member Author

andig commented Aug 4, 2025

Wir haben gethomepage/homepage#5630 vergessen :/

iseeberg79 added a commit to iseeberg79/openems that referenced this pull request Aug 12, 2025
evcc API changes

see evcc-io/evcc#22299
testing current and old API responses
prepare-commit.sh  corrections
@TheNinth7
Copy link

Unfortunately, the integration with openHAB is currently broken — the evcc binding no longer works with the latest evcc version.

I haven’t opened a PR yet, as I need another user to help test and finalize it.

Perhaps I can help. However, I’m running openHAB in Docker, so I can only use what’s available as a Docker image or what can be installed into an existing installation via Karaf.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

infrastructure Basic functionality needs documentation Triggers issue creation in evcc-io/docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.