Look into renaming metadata and data fetching RPCs

[tiyash-basu-frequenz]

ATM, we have the following methods for getting metadata and data:

• ListComponents: Lists all components and their metadata.
• ListConnections: Lists all connections between components.
• GetComponentData: Streams component data from service.
• GetMetadata: Returns only the microgrid metadata.

The ListComponents and GetMetadata RPC names could be confusing.

The rationale for ListComponents listing component metadata is convenience. It would otherwise be tedious to fetch just component IDs with ListComponents, and then fetch metadata for specific component IDs using something like GetComponentMetadata.

The rationale for GetMetadata is that it is in the Microgrid service, and Microgrid::GetMetadata would refer to the metadata of the microgrid.

So, do these RPC names make sense, or do they need to change?

cc @leandro-lucarella-frequenz @sahas-subramanian-frequenz

[leandro-lucarella-frequenz]

There are several points here IMHO.

• I think it would be good to have a distinction at the API level for stuff that don't change unless the microgrid is restarted and stuff that changes dynamically.
• It would be good to have consistent naming for stuff that produces a stream and stuff that is meant to be queried once / polled.
• From those 2 points it becomes apparent that static stuff should be provided via a query interface and dynamic stuff through a streaming interface.

If I understand correctly, only GetComponentData changes dynamically. All the rest (metadata in general, and the graph representation, i.e. nodes and edges) is static. If this is correct, I think we should have:

• GetComponents: includes the metadata as now, it is all part of the static component graph.
• GetConnections: same as now
• GetMicrogridMetadata: I think otherwise is not clear that it is only the microgrid metadata
• StreamComponentData: Makes it super obvious that it is a streaming interface.

I don't see a reason for Get vs List, that's why I'm using Get which seems more natural (not sure if there is some convention for this in gRPC).

BTW, do we even need to separate components, connections and microgrid metadata? Could we have a GetMicrogrid method that returns something like this:

message Microgrid {
    Metadata metadata = 1;
    ComponentList components = 2;
    ConnectionList connections = 3;
}

In this case I think it is much clearer that metadata is the microgrid metadata.

[tiyash-basu-frequenz]

StreamComponentData: Makes it super obvious that it is a streaming interface.

BTW, do we even need to separate components, connections and microgrid metadata? Could we have a GetMicrogrid method that returns something like this:

Both LGTM

Then we should proceed with the following:
a. adding StreamComponentData
b. adding GetMicrogrid
c. removing GetMetadata, ListComponents, ListConnections, GetComponentData

I don't see a reason for Get vs List, that's why I'm using Get which seems more natural (not sure if there is some convention for this in gRPC).

List makes more sense to when returning a collection of items. It is also a convention for standard methods. However, we are going to deprecate these methods.

[tiyash-basu-frequenz]

After thinking about this a bit, I think the filters in ListComponents and ListConnections are quite useful on the command line for debugging, especially for microgrids which have a large number of components and connections.

So, in order to keep using existing implementations, I'd propose a revision to what we agreed on before:

• we rename GetComponentData to StreamComponentData as we discussed before,
• we rename GetMetadata to GetMicrogridMetadata, also as proposed by Luca before,
• we rename ListComponents to ListComponentMetadata.
• we leave ListConnections as is.

Does this sound okay?

[sahas-subramanian-frequenz]

yup, I agree that keeping the methods is more convenient.

[tiyash-basu-frequenz]

I have added the changes in a new PR: #43

[leandro-lucarella-frequenz]

OK for me too, but I wouldn't rename ListComponentMetadata then, it returns a list o Component, not ComponentMetadata. And you'll still have to do component.metadata to dig into the metadata. It sounds weird to me.

Maybe rename microgrid.Metadata to microgrid.MicrogridMetadata to have the methods and messages it returns completely symmetric?

• ListComponents -> list of Component
• GetMicrogridMetadata -> MicrogridMetadata
• StreamComponentData -> stream of ComponentData
• ListConnections -> list of Connection

[tiyash-basu-frequenz]

Sounds good to me. Will update the PR.

[tiyash-basu-frequenz]

So, if we all are in agreement here, then I'll create an issue for this, make the changes, and add it to the v0.12.0 milestone.

[tiyash-basu-frequenz]

Okay, the PR #43 has been updated.

I think we can conclude this discussion here. Thank you very much for your valuable feedback! 🚀