Welcome to the collaboration space for FDC3 Maintainers and Contributors!

As FDC3 is both a standard and publishes several software libraries there are multiple places that a change to the API will nee to be reflected in. These are covered below:

How big the change being made is will affect how much documentation needs to be created for it. If you are creating a whole new API function or significantly extending it then it may need a new "functional use case" in the API overview to explain the need for it.

If the new feature creates a capability, then it should be described in a later section (as Raised Intents and Channels are). Add to the existing sections where it makes sense to do so.

Next add or update the function in the API reference pages:

• https://fdc3.finos.org/docs/api/ref/DesktopAgent
• https://fdc3.finos.org/docs/api/ref/Channel
• https://fdc3.finos.org/docs/api/ref/PrivateChannel

And add an types, metadata objects, errors or events to the relevant pages:

• https://fdc3.finos.org/docs/api/ref/Types
• https://fdc3.finos.org/docs/api/ref/Metadata
• https://fdc3.finos.org/docs/api/ref/Errors
• https://fdc3.finos.org/docs/api/ref/Events

Note that you will need to add (or solicit) defintions in TypeScript, .Net and GO as we provide them in all 3 languages.

You may need to update the WCP and DACP documentation pages if your change affects them. However, these pages try to avoid giving many examples of messages, instead linking out to the schemas that define them , which reduces the changes we need to make. If creating a new API you will to add links to its schema and section for it in the DACP. But if only adding new arguments, you may not need to make any changes.

Next you need to update the TypeScript types for the API in /packages/fdc3-standard/ and create any new interfaces etc. needed. The changes should be very similar to those in the documentation, where we give the same TypeScript defs. You want them to be identical so you can copy & paste between them. I.e. the markdown for the documentation entry is identical to the jsDoc comment in the TypeScript file.

API calls are also represented in the FDC3 for Web messaging schemas in /packages/fdc3-schema/schemas/. These have to include a Request and Response message for all API calls (see the protocol docs for details). Any objects type definitions (e.g. for things like IntentResolution or AppIntent) should go in packages/fdc3-schema/schemas/api/api.schema.json.

The schemas are used to generate the https://github.com/finos/FDC3/blob/main/packages/fdc3-schema/generated/api/BrowserTypes.ts file. Creating the schemas in the right directory with the .schema.json extension should be enough to get them added to the generation.Generation should be run via:

cd packages/fdc3-schema/
npm run generate

The DesktopAgentProxy implementation returned by getAgent (fdc3-get-agent package) is in /packages/fdc3-agent-proxy. It will need to support any new functions or arguments to functions and pass them along in messages to a browser-based Desktop Agent. This is the 'client-side' part of FDC3 for Web.

The updated schemas and DesktopAgent TypeScript types should both get picked up once saved - where a new function was added, for example, you should see errors where the DesktopAgentProxy is now no implementing the interface fully. Changes will be needed to implement support for the new function or arguments, which will make use of the updated BrowserTypes generated from the updated schemas.

FDC3 for Web's reference implementation (/toolbox/fdc3-for-web/fdc3-web-impl) is used to implement tests for the getAgent() and DesktopAgentProxy implementation, by providing a 'server-side' implementation (terrible terminology - this is the DesktopAgent running in a browser window). It will need to be updated to handle its end of the DACP protocol to make the fdc3-agent-proxy part testable.

Tests are needed for both sides of the implementation (to maintain coverage), in:

• /packages/fdc3-agent-proxy/test
• /toolbox/fdc3-for-web/fdc3-web-impl/test

Need to be applied in the reference docs (/website/docs/api/ref), TypeScript comments (/packages/fdc3-standard/src/api), and JSON Schemas (/packages/fdc3-schema/schemas/api use the deprecated keyword: https://json-schema.org/understanding-json-schema/reference/annotations)