Proposed API changes #94

tim-dinsdale · 2019-05-09T10:31:22Z

For discussion, not final

src/api/channel/channel.ts

docs/api/api-spec.md

rikoe · 2019-05-09T16:19:34Z

src/api/channel/channel.ts

+     * using the top-level FDC3 `broadcast` function, or using the channel-level {@link broadcast} function on this 
+     * object.
+     * 
+     * NOTE: Only non-default channels are stateful, for the default channel this method will always return `null`.


null or undefined? The latter feels more like idiomatic JavaScript to me - someone could explicitly set the value to null.

src/api/channel/channel.ts

zhenyakovalyov · 2019-05-20T13:06:29Z

docs/api/api-spec.md

+2. The 'private' or 'app' ones, which have a transient identity and need to be revealed
+3. The 'global' one which is available to everyone.
+
+Additionally there is a 'default' channel which serves as /dev/null and satisfies a possible requirements that all apps connect to one channel.


Could you please clarify the use-case for the default channel?

This fragment of doc is now out of date - there is no 'global', just the 'default' channel which acts as a way of retconning the old FDC3 global context into this scheme. Are you ok with that?

src/api/channel/channel.ts

vmehtafds · 2019-05-23T19:18:14Z

docs/api/api-spec.md

+
+The 'public' channels include a 'default' channel which serves as the backwards compatible layer with the 'send/broadcast context' above. There are some reserved channel names for future use. Currently this is just 'global'.
+
+To find a desktop channel, one calls


I am trying to understand how apps are going to use this API. Looking forward to some pseudo code demonstrating the three use cases we talked in the meeting.

I would like to know how an app associates itself with a channel or does a DesktopAgent puts an app in a channel (i.e. in the later case app knows nothing about channels). I was imagining some sort of joinChannel() api somewhere.

Also how this separate channel.broadcast() function is going to work. Is this something an app will call? I think the idea was app doesn't even need to know about channels. Will an app just use regular top level fdc3.broadcast() and the DesktopAgent intercept that and will then use the channel.broadcast() to route it accordingly? How are those two separate broadcast() play nicely with each other.

Same thing about addBroadcastListener() vs addContextListener(). What goes in the app vs the desktopAgent?

Hopefully some code around use cases will clear these things.

In terms of an app associating itself with a channel, something in the app will call getDesktopChannels, will find the channel it needs by checking the members of the DesktopChannelVisualIdentity interface, and will squirrel that away, plus the listener it got from subscribing to it.

In terms of the classic fdc3.broadcast() vs channel.broadcast(): the code is suggesting that one of the desktopChannels will be called 'default', and that if you call fdc3.broadcast() you will send to this channel and vice-versa. In other words, that channel is a facade to the existing single global context.

rikoe · 2019-06-27T15:03:19Z

src/api/channel/channel.ts

+    /**
+     * A user-readable name for this channel, e.g: `"Red"`
+     */
+    name?: string;


displayName would be slightly more descriptive, as discussed on our recent working group call.

rikoe · 2019-06-27T15:06:59Z

src/api/channel/channel.ts

@@ -0,0 +1,157 @@
+type ChannelId = string;
+
+declare interface Listener{    


We should reuse https://fdc3.finos.org/docs/1.0/api/DesktopAgent#listener for this, which is already ratified as part of v1.0 spec.

ColinEberhardt · 2019-07-03T05:41:06Z

docs/api/api-spec.md

+1. The 'public' or 'desktop' ones, which have a well understood identity. One is called 'default'.
+2. The 'private' or 'app' ones, which have a transient identity and need to be revealed
+
+The 'public' channels include a 'default' channel which serves as the backwards compatible layer with the 'send/broadcast context' above. There are some reserved channel names for future use. Currently this is just 'global'.


There are some reserved channel names for future use. Currently this is just 'global'.

For this to be workable, all reserved words need to be declared at the point this API is released, otherwise application developers aren't able to avoid naming collisions.

ColinEberhardt · 2019-07-03T05:41:26Z

src/api/channel/channel.ts

+    public readonly type: string;
+
+    /**
+     * Broadcasts the given context on this channel. This is equivilant to joining the channel and then calling the 


s/equivilant/equivalent

ColinEberhardt · 2019-07-03T06:48:59Z

src/api/channel/channel.ts

+     * within the set of channels registered with the service.
+     * 
+     * In the case of `desktop` channels (see {@link DesktopChannel}), these id's _should_ persist across sessions. The 
+     * channel list is defined by the service, but can be overridden by a desktop owner. If the desktop owner keeps 


This is introducing a new concept "desktop owner", which isn't defined in our spec:

https://fdc3.finos.org/docs/1.0/api/api-spec

Any new terminology should be clearly defined in the documentation!

nkolba

@tim-dinsdale @rikoe - I've made updates based on the WG feedback (and votes). Can you please check the work and if good, merge!

rikoe · 2019-08-09T09:56:50Z

@nkolba @tim-dinsdale Next we need to get the website documentation updated for this.

Proposed API changes

27ab302

finos-admin added the cla-present label May 9, 2019

ColinEberhardt reviewed May 9, 2019

View reviewed changes

src/api/channel/channel.ts Outdated Show resolved Hide resolved

some docs and examples

b501929

rikoe suggested changes May 9, 2019

View reviewed changes

rikoe added the api FDC3 API Working Group label May 9, 2019

zhenyakovalyov reviewed May 20, 2019

View reviewed changes

Better specs for private channels; identities

5008f6e

ColinEberhardt reviewed May 23, 2019

View reviewed changes

src/api/channel/channel.ts Outdated Show resolved Hide resolved

ColinEberhardt reviewed May 23, 2019

View reviewed changes

src/api/channel/channel.ts Outdated Show resolved Hide resolved

ColinEberhardt reviewed May 23, 2019

View reviewed changes

src/api/channel/channel.ts Outdated Show resolved Hide resolved

vmehtafds reviewed May 23, 2019

View reviewed changes

Minor cleanup

9ce271f

rikoe reviewed Jun 27, 2019

View reviewed changes

ColinEberhardt reviewed Jul 3, 2019

View reviewed changes

Nicholas Kolba added 2 commits August 8, 2019 16:31

update spec based on WG feedback

558598b

Update channel.ts

5229f62

nkolba approved these changes Aug 8, 2019

View reviewed changes

rikoe approved these changes Aug 9, 2019

View reviewed changes

nkolba merged commit 9c2c7b5 into finos:master Aug 9, 2019

rikoe mentioned this pull request Oct 29, 2019

Create documentation for new Channels API #126

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Proposed API changes #94

Proposed API changes #94

tim-dinsdale commented May 9, 2019

rikoe May 9, 2019

zhenyakovalyov May 20, 2019

tim-dinsdale Jun 25, 2019

vmehtafds May 23, 2019

tim-dinsdale Jun 25, 2019

rikoe Jun 27, 2019

rikoe Jun 27, 2019

ColinEberhardt Jul 3, 2019

ColinEberhardt Jul 3, 2019

ColinEberhardt Jul 3, 2019

nkolba left a comment

rikoe commented Aug 9, 2019


		The 'public' channels include a 'default' channel which serves as the backwards compatible layer with the 'send/broadcast context' above. There are some reserved channel names for future use. Currently this is just 'global'.

		To find a desktop channel, one calls

		@@ -0,0 +1,157 @@
		type ChannelId = string;

		declare interface Listener{

Proposed API changes #94

Proposed API changes #94

Conversation

tim-dinsdale commented May 9, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nkolba left a comment

Choose a reason for hiding this comment

rikoe commented Aug 9, 2019