Add /intents and /contexts endpoints to the AppD API

[kriswest]

Enhancement Request

When working with an app directory it would be useful to be able to request the list intents and contexts used by apps listed in the app directory. This information is already retrievable, to a certain extent, from the individual records, however, doing so requires interesting all the records and collecting up the information.

Adding intent and context endpoints to the API would allow:

• Pre-population of search/browsing interfaces for filtering apps by supported intents and contexts
  • Note the underlying data for such searches may be significantly improved by Extend AppD application definition to support describing an app's use of interop (App Channels, User Channels & Intents) #247
• The use of these endpoints to provide display data (e.g. displayName)
  • There is a long-standing issue with intents in that each app may configure a different display name for the same intent: The AppIntent interface incorrectly describes an intent #312

Proposed endpoints:

route	REST verb	Description
/v2/intents	GET	Retrieve a list intent supported in the app directory instance
/v2/intents/{intent name}	GET	Retrieve detail on a particular intent
/v2/contexts	GET	Retrieve a list of contexts referenced in the app directory instance
/v2/contexts/{context type name}	GET	Retrieve detail on a particular context

The detail endpoints for an individual intent and context types could:

• Be replaced by returning all the detail under the main endpoints
• Provide a list of the apps that reference it
• Provide a schema or similar detail for the context (however this could/should be optional as not every implementation will want to provide references for standardized contexts)

A number of AppD implementations already provide these endpoints, including electron-fdc3 and the AppD browser demoed to the group by Citi.

It has also been proposed in the past that it is necessary to provide tools to govern internal/proprietary intents and contexts and that this has been implemented in the past through an extension to an app directory implementation. These would be natural extension to the proposed details endpoints.

[kriswest]

@nkolba it'd be interesting to hear what you use these endpoints for and the functionality they have in electron-fdc3
@Qiana-Citi @RandallDang-Citi likewise it'd be really interesting to hear more about your use of these endpoints at Citi.

[RandallDang-Citi]

@nkolba it'd be interesting to hear what you use these endpoints for and the functionality they have in electron-fdc3 @Qiana-Citi @RandallDang-Citi likewise it'd be really interesting to hear more about your use of these endpoints at Citi.

@kriswest Thanks for the invitation, Qiana will join.

[nkolba]

@RandallDang-Citi the electron-fdc3 client doesn't currently use these endpoints. Definitely many good potential uses though (such as creating a richer search experience).

[pierreneu]

@kriswest We are looking into this to be able to dynamically show to the user the locally available intents/apps on a fdc3 object.
This fdc3 object could be a static one (for example a fdc3.contact object from a user profile card), or a dynamic one (a fdc3 context object present in a chat message).

[kriswest]

@kriswest We are looking into this to be able to dynamically show to the user the locally available intents/apps on a fdc3 object.
This fdc3 object could be a static one (for example a fdc3.contact object from a user profile card), or a dynamic one (a fdc3 context object present in a chat message).

@pierreneu at present the best way to do that is to use the findIntentsByContext and raiseIntentForContext functions of a Desktop Agent. The former will return a list of intents and apps for each intent that make use of that context type (each intent returned will have at least one app as that is how they are discovered), while the latter will present the same data in the Desktop Agent's own resolver UI.

If you need to do this without a real context then you'd have to pass in a dummy context of the right type - in most cases, I imagine implementations will only use the type field to determine the options - although it's worth making sure the object is valid (i.e. contains required fields). This is where the proposed endpoints would come in handy as you could retrieve a list of context types supported - although as a Desktop Agent could be connected to multiple app directories, and there is no way to get at that list, we might want to consider adding a function to the Desktop Agent API to pass-through a consolidated list (of either the intents and contexts from all appDs, or at least the list of AppD URLs in use + any apps configured another way)...

There was some resistance to another proposal in the past (#311) that would have made similar information available (a list of applications, although as proposed it didn't have the list of supported intents and contexts for each, only the AppMetadata). That issue remains open but needs additional use-case information to be added to move it forward. Hence, the more detail on use-cases that can be provided for either issue, the better!

[kriswest]

Notes from #802:

• A number of participants (including @nkolba and @kriswest) felt that the proposed /intents and /contexts appD endpoints are useful for both development and governance use (at least one firm has demonstrated a web UX based on similar endpoints).
• However, adding API endpoints that pass through this information was not considered necessary or wise as it makes it easier for an application to gather and leak information about the desktop environment (@nkolba @kriswest @openfin-johans).
  • Similar, but more limited, functionality is already available in the form of the findIntentsByContext and raiseIntentForContext API calls, which will return intent and resolution to app options for a specific context (adding a list of all know contexts makes mining information with these calls trivial, however, the calls as they stand serve a valid usecase.
  • The same thought applies to an API call to retrieve the details of the appD URLs in use. Apps running in the context of a Desktop Agent generally do not need this information (although vendors would value the information, firms using the agents are unlikely to want that information to leak).
• (Silent) consent was sought and received to move forward with proposing new appD API endpoints for `/intents' and '/contexts' and to NOT make any additions the Desktop Agent API.