Should the DesktopAgent API should rely on appId and/orAppMetadata rather than name?

[kriswest]

At the last AppD discussion group meeting it was proposed that we arrange a one-off meeting to discuss the use of the name field in the FDC3 API and whether that usage should be deprecated in favour of an approach based on appId.

The use of the (non-unique, machine-readable, but 'friendly') name field to refer to apps in the FDC3 API has long been criticised due to the fact it doesn't differentiate versions of the same app (and has no disambiguation logic) nor apps bearing the same name in different app directories. The appId field, on the other hand, is unique within an app directory and can be fully qualified with the domain name of the app directory that supplied it.

EDIT: FDC3 2.0 deprecated API call signatures based on name and now focuses on those based on AppIdentifier (appId) and AppMetadata (where appId is required and name optional)

[kriswest]

Note: There is an existing proposing the deprecation of the name field in the Desktop Agent API, in favour of the AppMetadata object (already supported in the same places) which can specify both appId and instanceId, allowing us to address both apps and instance of apps in API calls (e.g. for targeting a raised intent):

• Deprecate use of the string name field in favour of AppMetadata #506

That issue should also (but doesn't yet) propose updating AppMetadata such that name is optional and appId is required (where the reverse is the current situation).

[kriswest]

Hence the proposed changes are:

interface AppMetadata {
  name: string;
  appId?: string;
  version?: string;
  title?: string;
  ... etc.
}

changes to:

interface AppMetadata {
  appId: string;
  name?: string;
  version?: string;
  title?: string;
  ... etc.
}

We would then drop the type TargetApp type, which is just string | AppMetadata and helps us avoid duplicate function signatures currently, and split the function signatures up, with the versions using name becoming deprecated. I.e.:

interface DesktopAgent {
  // apps
  open(app: TargetApp, context?: Context): Promise<void>;
  ...
  
  // intents
  ...
  raiseIntent(intent: string, context: Context, app?: TargetApp): Promise<IntentResolution>;
  raiseIntentForContext(context: Context, app?: TargetApp): Promise<IntentResolution>;
  ...
}

changes to:

interface DesktopAgent {
  // apps
  open(app: AppMetadata, context?: Context): Promise<void>;
  ...
  
  // intents
  ...
  raiseIntent(intent: string, context: Context, app?: AppMetadata): Promise<IntentResolution>;
  raiseIntentForContext(context: Context, app?: AppMetadata): Promise<IntentResolution>;
  ...

  //deprecated
  open(name: String, context?: Context): Promise<void>;
  raiseIntent(intent: string, context: Context, name?: String): Promise<IntentResolution>;
  raiseIntentForContext(context: Context, name?: String): Promise<IntentResolution>;
}

[thorsent]

There are some semantics to consider:

Will the Fully qualified requirement for AppID be MUST or SHOULD? Without the fully qualified requirement, implementations might encounter collisions (e.g. AppId: "chart" vs. AppId: "[email protected]"). But the cost of this precision is complexity.

Regarding title, the word "title" implies a phrase, more akin to document.title, e.g. "Technical charting and analysis". This is something that should be display only, never being relied upon for logic.

Arguably, name sits somewhere in the middle of these two but comes at the cost of complexity and ambiguity.

I would side with deprecating name and setting full-qualification of AppId as a SHOULD. I wouldn't make name optional since it shouldn't be used for display nor can be relied upon for logic.

[kriswest]

I believe we should make name optional at the same time as deprecating it to ease the transition. When using AppMetadata as a target you could then write {appId: "myAppId@whatever"}, otherwise it'd have to be {appId: "myAppId@whatever", name: "myApp"} which I think would perpetuate name for longer (@thorsent and I have discussed this off to the side).

[kriswest]

I agree with the idea of making full-qualification of AppIDs a SHOULD.

[bingenito]

What would be a use case for the name field moving forward? Would there be a case to display that if available as opposed to title?

[kriswest]

By deprecating it we're saying it should not have a role in future. I only propose deprecation rather than removal for governance reasons (see deprecation policy) and so that it is easier to support applications still using name. Hence the proposal is to retain name as optional and deprecated - with the intention of removing it in a future FDC3 major version.

This would allow apps that use API calls based on name rather than AppMetadata to continue to work in a 2.0 implementation, but hopefully discourages any new implementations from using them.

[kriswest]

Note that there is the title field in both an appD record and AppMetadata which can be used for a human-friendly name for an app (so we don't need name for that).

[kriswest]

A colleague working on our own Desktop Agent implementation (@mhmcclung) gave the below justification for the deprecation and (eventual) removal of name from the API:

the issues I see:
A) Given appId is the unique identifier, then continuing to allow the use of name in TargetApp will force the spec into one of these options:

• an fdc3.open can produce ambiguous results, or
• an fdc3.open that is ambiguous must fail, or
• an fdc3.open that is ambiguous must invoke the UIResolver.

B) Also, independent from the extra API complexity, keeping the name forces each DA to handle more.

C) Plus as I mentioned before, if the name was limited to just allowing multiple versions of the same app, then I still don't see an implementation path that doesn't creates app-authentication ambiguity, which I don’t think would be acceptable from a security perspective.

So specifying one unique ID to drive all FDC3 logic will definitely simplify things, without any loss of functionality that I'm aware of.

I note the above applies equally to fdc3.open and fdc3.raiseIntent with a target specified.

[kriswest]

as name was deprecated in 2.0 this discussion is now closed.