[Asset Manager] Allow retrieval of human readable names for asset EANs via API

[jasonrhodes]

Summary

API callers should receive the most human-readable name available to the API when returning asset information, in order to give the most context to users. In addition, end users should be able to update this human-readable name for a given EAN (Elastic Asset Name, the identifier for a given asset instance) and have it persist.

Acceptance Criteria

• API method exists to return a human readable name for an asset via EAN
• API method exists to store a human readable name for an asset via EAN
• Note: this name is not guaranteed to be present in the asset documents should they be queried directly in Elasticsearch, so this is only a feature available via the Assets API

Details

The API should go through a series of steps when attempting to return this name, something similar to:

1. Look in some store external to the main assets-* store for a mapping between an asset's EAN and a user-chosen, persisted name.
2. Use some heuristic for the specific asset kind + type, if one exists.
3. Use a generic asset heuristic (e.g. look for an "elastic-asset-name" tag stored with the asset, or similar)
4. Use the asset's ID as a last resort

This name cannot be stored on the asset documents themselves because of the time-series nature of the asset documents—if we attempted to store a user-chosen name on the asset documents, it would need to be written to every single timestamped document for that asset, as well as the future incoming documents. For this reason, we should opt for storing this information in a separate index or Kibana saved object. Where it's stored is an implementation detail that is irrelevant to the caller.

[miltonhultgren]

Do we expect the current API endpoints that return a list of assets to use this new endpoint to enrich that list with the human readable name before returning the list, or is that a step we expect API consumers to coordinate per asset when they want to display it?

[jasonrhodes]

@miltonhultgren one of those, for sure! :) Do you think the design of this API is dependent on which of those paths we take later?

[miltonhultgren]

No, I was mostly thinking about if this needs to be an individual endpoint or just a library function for the resolution flow. But the fact that there is a resolution flow with it's own data access steps might mean it'll be a little bit slower so exposing it as an endpoint would allow us to be more flexible about when we pay the cost of finding the display name.

[jasonrhodes]

I was mostly thinking about if this needs to be an individual endpoint or just a library function for the resolution flow.

Can you elaborate on the difference, there? I see this as starting out as an individual "endpoint" (no REST needed, so more of a TS method) that is a library function, if I understand correctly. Eventually, I think the asset retrieval flows may incorporate this "get" method into their other methods, so that they can return the display name with the lists of assets, but I didn't want to conflate that work yet, while we determine how we want to store and retrieve this info.

[miltonhultgren]

Right, for me endpoint = HTTP endpoint (whether it's REST or not, an entry to a HTTP system). So this issue is about building the TypeScript function to load the display name, and we'll decide later who will call that function (existing asset endpoints or some new endpoint).

[jasonrhodes]

Yep, as far as I know, HTTP endpoints aren't really a part of this effort because they aren't a usable interface in Kibana (outside of being a connection from within a plugin's own client talking to its own server, as an implementation detail only). So the interface we will need to provide from asset manager is going to be all TS methods. I know we began with HTTP/REST docs, but mostly because they were the easiest way to explain what we were trying to do and I wasn't fully aware of the extreme limitations of REST in Kibana.

If we don't have one already, I'll log an issue to rewrite the existing plugin docs to reflect this and to focus on the TS API.

[miltonhultgren]

Got it, that's news to me but it makes sense!