add fields param to the asset-listing endpoints, controlling fields in response

[nhoening]

Until now, the asset index endpoint would return all possible asset information, including child assets, sensors, flex-config and model.

This made listings hard to read (as a developer) and also we're sending a lot of unnecessary data.

• Add new field fields parameter to asset index endpoint, with sensible default
• Make asset listing pages use it
• Improve some other schema field descriptions
• Make endpoint for public assets also use the new parameter
• Added changelog item in documentation/changelog.rst and api changelog

Closes #1887

Look & Feel

Nothing should really change in the UI.

The API endpoints should return less data by default, testable in SwaggerUI.

Further Improvements

We could investigate to do the same for sensor listing endpoints, but they don't send that much data per entry.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #30839488 | 📁 Comparing 3c8187c against latest (1e28403)

🔍 Preview build

Show files changed (6 files in total): 📝 6 modified | ➕ 0 added | ➖ 0 deleted

File	Status
changelog.html	📝 modified
genindex.html	📝 modified
_autosummary/flexmeasures.api.common.schemas.assets.html	📝 modified
_autosummary/flexmeasures.api.v3_0.assets.html	📝 modified
api/change_log.html	📝 modified
api/v3_0.html	📝 modified

[Flix6x]

Good idea to have a new field for this.

[Flix6x]

This default appears to be a breaking change in our API. I'm guessing we are currently returning all db columns as fields? API clients may depend on that feature.

[nhoening]

I propose including a warning in the changelog to this effect.

[Flix6x]

Unfortunately I don't think that is enough, even though I'd like it to be. As a host, I'd require a migration plan to make sure I can still upgrade without breaking my client's code. I instead suggest returning all fields by default, purely for backwards compatibility. Of course, in FM's own UI, we can still reduce the number of fields queried.

Slightly better would be to freeze the default (to those fields currently returned), such that at least any new field added in the future won't end up also returned by default.

[nhoening]

I am on the other side of the fence. Too much restriction and care like this slows us down too much.

There is one other thing we can do:
We can put the question to the community actually, on slack and the TSC.
I believe that we are in contact with most anybody who is already running with custom code.

[Flix6x]

Good idea involving the community. Here's an example of client code that I suspect would break: https://github.com/V2G-liberty/addon-v2g-liberty/blob/7eafe2e22c88cf89da61873d5f02ecbdcc8e8a40/v2g-liberty/rootfs/root/appdaemon/apps/v2g_liberty/fm_client.py#L250

We're now already two steps into formulating a migration plan: informing the community and identifying necessary adjustments to client-side code. I share your concern about slowing ourselves down.

[nhoening]

I will inform the community.

What can we to identify necessary adjustments to client-side code, or to help people do it?