search

w3c-ccg / vc-api

A specification for an HTTP API used to issue and verify Verifiable Credentials.
https://w3c-ccg.github.io/vc-api
Other
123 stars 47 forks source link

Clarify the distinction between exchangeId and localExchangeId #425

Open jrhender opened 2 weeks ago

jrhender commented 2 weeks ago

When calling Create Exchange, an exchangeId is returned. However, the Participate in an Exchange endpoint has a localExchangeId URL path parameter.

Looking at the Exchange Example, my assumption is that the Create Exchange endpoint was only called once. I think this must be the case as there is a single workflowId 123 and a workflow can only have single possible starting step. Therefore, on might expect there to be a single exchangeId for the interactions in the example. However, the localExchangeId changes in the example from 123 to abc. I see the following possible explanations:

  1. localExchangeId is intended to be different from the exchangeId. In other words, a "local exchange" is essentially an instance of workflow step which is associated with the parent exchange. If this the case, it is unclear how the localExchangeId is determined (e.g. by the Owner Coordinator to pass to the client of the exchange).
  2. localExchange is the same as exchangeId and the change from 123 to abc is a mistake.

I think that further discussion and explanatory text on this point would be helpful for implementors of the workflow features.

dlongley commented 1 week ago

In short, an exchange has two IDs, a fully qualified one (full URL) and a relative one (just the "slug" or "path" part). I don't think we want two different properties in the data model of exchanges for this -- and that we just want the relative value to be returned, i.e., exchange.id == '<relative exchange ID>'.

We will need a separate name to describe the relative ID when talking about it as a URL path parameter, however, because it needs to be distinguished from other slugs/path params like the relative workflow ID (which appears in the full exchange ID URL).

We do need to fix up the YAML files that describe what information is returned when creating an exchange. I believe there should be an id field that holds the relative ID only (slug only, i.e., "localExchangeId" or the relative "path" parameter value) and that we should remove the exchangeId property. We should only use the name exchangeId, I think, if we're expressing information that isn't in an exchange itself. This would be consistent with how we use credentialId to refer to a fully qualified (full URL) to identify a credential, but the ID doesn't appear in the credential.

We need to settle on a name for what we're calling the "slug"/"path" thing that appears in the URL / routes as a local/relative identifier for the exchange. Maybe we even want to use "relative" in name for that.

jrhender commented 1 week ago

Ok, thanks for the clarification @dlongley . Your points make sense to me 👍 .

I think then that the exchange example should adjusted to have the same localExchangeId for both of the participate calls. PR here to implement this: https://github.com/w3c-ccg/vc-api/pull/427