API endpoints MUST specify the component (Issuer App, Issuer Service, etc.)

[jandrieu]

I feel like a broken record on this one.

The API is currently unusable--even for us as collaborators--because we are unable to distinguish which endpoints are on which component.

For example, there is zero chance that I would support a presentations/verify endpoint on the Verifier App, but it makes perfect sense on the Verifier Service. In fact, I would say it is required on the Verifier Service.

It is impossible for us to even have these conversations with the current structure of the repo, where all of the endpoints could be attached to any component.

NOTE that the reason we introduced Apps and Services is precisely because people had legitimate uses for endpoints on the Verifier App that make no sense on the Verifier Service, and those who were thinking through different use cases had a hard time understanding why folks were suggesting that the Verifier needed these endpoints. Turns out, they make sense for the App, but not the service.

Please update and restructure this spec to identify WHICH component is intended for each endpoint.

[dlongley]

+1 to the above. I also think we should disambiguate what "App" means, especially given that client side apps such as Web and native apps exist -- and these are different from a server side "App", especially with respect to security / trust boundaries.

[jandrieu]

@dlongley Does the definition here satisfy that disambiguation? https://w3c-ccg.github.io/vc-api/#apps

[dlongley]

@jandrieu, I don't think so -- it would need to clearly say that client components (like Web apps and native apps) are distinct from from the "app". But I think the name just needs to change to avoid the confusion. I think we should also have a name for a client component (again, which is often what "app" means in the Web / tech community).

[jandrieu]

Ah...

But client components are NOT distinct from the app. When breaking down the CHAPI flows, it was important to consider the browser, authn.io, the chapi polyfill, and wallet iframe contents as part of "the Holder App". To the extent that a Holder App has a standard API, the Veres Wallet would need to be updated to support those endpoints in some way.

For example, CHAPI does not currently support asynchronous callbacks for out-of-band delivery of credentials. This likely means that it would NOT be conformant with an API specification that required supporting asynchronous flows. (And many of us feel that's an important use case.)

I have no doubt that it can be updated to support such flows, but it is the Holder App as a whole that needs the support, regardless of how that App is architected. What you might change in the browser or the polyfill or the Veres Wallet API is immaterial, as long as the end result supports the Holder App API as a whole.

[msporny]

During the 2023-01-31 and 2023-02-07 telecons, the group went over the following endpoints and assigned them to components and expected callers:

Issuing

• POST /credentials/issue
  • Components: Issuer Service
  • Expected callers: Issuer Coordinator
  • Discussion: There might be a desire for something on Issuer Coordinator that the Holder Coordinator calls to ask for a credential from the coordinator.
• POST /credentials/status
  • Components: Status Service
  • Expected callers: Issuer Coordinator
  • Discussion: Should this go on the Issuer Service (to change state) and then Status Service (to publish state)? POST is for updating state, but we haven't defined GET for the status list yet.
• GET /NEW_ISSUER_SERVICE_PATH/credentials (Issuer Service)
  • Components: Issuer Service
  • Expected callers: Issuer Coordinator (for listing VCs that have been issued)
  • Discussion: Different interpretations on this endpoint -- list of credentials that have been issued (Issuer Coordinator -- when managing all credentials issued)
• GET /NEW_ISSUER_COORDINATOR_PATH/credentials (Issuer Coordinator)
  • Components: Issuer Coordinator
  • Expected callers: Holder Coordinator (for listing VCs that could be issued to them)
  • Discussion: List of "VC types", or "a number of VCs", that are available (Issuer Coordinator? maybe?) -- e.g., "You have a transcript available for pickup, go to this exchange endpoint 'abcd1234' to pick it up")
• GET /credentials/{id}
  • Components: Issuer Service
  • Expected callers: Issuer Coordinator
  • Discussion: We need to explore what happens w/ the "I have a list with types of VCs that could be issued" use case outlined in... if the Issuer Coordinator exposes this endpoint, what is the functionality? Is it equivalent to an exchange, or is there something else that goes on here?
• DELETE /credentials/{id}
  • Components: Issuer Service
  • Expected callers: Issuer Coordinator
  • Discussion: Presumption here is that status is changed to revoked in an atomic operation, or Issuer Coordinator ensures that "the right thing happens" based on its business rules.

Verifying

• POST /credentials/verify
  • Components: Verification Service
  • Expected callers: Verification Coordinator
• POST /presentations/verify
  • Components: Verification Service
  • Expected callers: Verification Coordinator

Presentation

• POST /credentials/derive
  • Components: Holder Service
  • Expected callers: Holder Coordinator
  • discussion: It's not clear whether BBS derives another "verifiable credential" or if a "verifiable presentation" is the "thing that is derived".
• POST /presentations/prove
  • Components: Holder Service
  • Expected callers: Holder Coordinator
  • discussion: We didn't finish bikeshedding "prove" vs. "derive"
• GET /presentations
  • Components: Holder Service
  • Expected callers: Holder Coordinator
  • discussion: Could be on Verifier Coordinator if they collect presentations they've received previously? Do we need this (in general) for async / HTTP callback-based approaches? Query could come over one channel, response could go back over another (this is what interact is used for today). Do we need a POST /presentations for the verifier to track presentations it's received?
• GET /presentations/{id}
  • Components: Holder Service
  • Expected callers: Holder Coordinator
  • discussion: (repeat 2) Could be on Verifier Coordinator if they collect presentations they've received previously? Do we need this (in general) for async / HTTP callback-based approaches? Query could come over one channel, response could go back over another (this is what interact is used for today). Do we need a POST /presentations for the verifier to track presentations it's received?
• DELETE /presentations/{id}
  • Components: Holder Service
  • Expected callers: Holder Coordinator
  • discussion: (repeat 3) Could be on Verifier Coordinator if they collect presentations they've received previously? Do we need this (in general) for async / HTTP callback-based approaches? Query could come over one channel, response could go back over another (this is what interact is used for today). Do we need a POST /presentations for the verifier to track presentations it's received?
• POST /exchanges/
  • Components: Issuer Coordinator, Verifier Coordinator, Exchange Service
  • Expected callers: Holder Coordinator
  • discussion: This endpoint is used to create endpoints.
• POST /exchanges/{exchange-id}
  • Components:
  • Expected callers:
  • discussion: if you POST nothing to the URL, you get back the VPR that brought you to this endpoint... OR, you can POST the VP to this endpoint and get a response (a VP in response, or another VPR w/ an interact field).
• POST /exchanges/{exchange-id}/{transaction-id}
  • Components:
  • Expected callers:
  • discussion: We haven't found a use case for this endpoint yet

[kezike]

Three questions/comments related to the GET /credentials endpoint (because we did not discuss this endpoint enough last call 😅):

• I noticed that you added an entry for GET /NEW_ISSUER_COORDINATOR_PATH/credentials. Is it proper to have endpoints at coordinators?
• Have we considered using query parameters for this endpoint? I know that we don’t typically meddle with query parameters in this group (possibly because of the potentially complex design space that it might introduce), but this seems as appropriate of a use case as I can imagine for such a design if we can restrain the parameter set. With this design, we could refine the set of credentials returned based on parameters such as type, credentialSubject ID, or other common fields in a credential. I can think of at least two potential arguments against this idea (with potential solutions in parentheses): -- 1) how to access nested fields in a credential (exclude these from the design space or use camelcase/underscore delimiting to represent depth to search in credential) and -- 2) how to represent a range for properties such as issuance date or numerical values (exclude these from the design space; design semantics that are common/relevant for the given property - e.g., expirationDate=DATE would search for credentials that have a date before DATE; use two-element arrays).
• I created this issue last summer that touches on some of the concerns in the previous point and adds a couple other suggestions as well. Perhaps that is a better channel for this discussion.

[PatStLouis]

I would like to point out something around GET /credentials endpoint (because now we definitely didn't discuss this enough!)

On the currently drafted api spec, the GET /credentials endpoint lies exclusively on the holder component, however it seemed taken for granted 2 weeks ago that it belongs on the issuer component. When was this change discussed/introduced? Why was it originally planned for a holder endpoint and now the endpoint was discussed as not being part of a holder service?

An important functionality of a holder is to display the credential it currently owns to its user. Why would this not be reflected through the vc-api? I understand the use case of storing issued credential from an issuer for auditing purposes, however this was discussed as optional and based on business' requirements.

[msporny]

The group discussed this on 2023-02-21 and had the following responses:

• I noticed that you added an entry for GET /NEW_ISSUER_COORDINATOR_PATH/credentials. Is it proper to have endpoints at coordinators?

Yes. It is proper to have endpoints at coordinators, largely when crossing trust/security boundaries.

@dlongley wondered whether /NEW_ISSUER_COORDINATOR_PATH/credentials should be one of these endpoints, depends on what authz mechanism is used. When trust boundaries are crossed, those are on coordinators... when they are not, they are probably not on coordinators. @jandrieu noted that this came out of traceability work... with "data ready", then party who is notified that there is a VC waiting for them, they call back to get VC that is waiting for them (this should be on issuer service) - API call got bumped to coordinator, they can expose if they so choose. Other point, what are "exchanges"? -- sense was that exchanges are a way to have a single URL that can do a complex set of interactions, setup for an end user of some type to call URL and have rest of components of call constructed -- what it seems like is exchanges is a way to overlay for semantic endpoints, if it's not managing redirect flow, then it doesn't have separate semantics, if it doesn't it's good, but then languaging here might need to be adjusted. Not sure what semantics of exchanges endpiont should be. @dlongley noted that that sounds like an "exchanges" URL use case... crosses trust boundary, should be using exhcnages endpoint. @PatStLouis noted that there was a difference on service it's the list of credentials that have been issued, on coordinator it's list of credentials that can be issued. Regarding exchanges, exchange was the component responsible for exchanging data/communication -- for example, could we define an exchange endpoint specific for DID Comm exchange? Could we have OIDC4VC on an exchange? Is that the idea w/ exchange? @jandrieu the exchange does something other than setup -- semantics seem to be getting confused... "we don't need it because we have exchanges" is a different mental model than what's been done to date. @dlongley re: exchanges... the answer is "yes"... DB has implemented exchanges w/ VC API and we've implemented exchanges w/ OID4VC. Something similar could be done w/ DIDComm ... it could be something we go on to further document, provide alternative protocols on an exchange endpoint to enable different wallets w/ protocols.

• Have we considered using query parameters for this endpoint? I know that we don’t typically meddle with query parameters in this group (possibly because of the potentially complex design space that it might introduce), but this seems as appropriate of a use case as I can imagine for such a design if we can restrain the parameter set. With this design, we could refine the set of credentials returned based on parameters such as type, credentialSubject ID, or other common fields in a credential. I can think of at least two potential arguments against this idea (with potential solutions in parentheses):

@dlongley noted that once you start using query parameters, you start running out of the ability to properly form queries and you end up moving to a POST-based query language to get the results you want. @PatStLouis noted that this might be left to the implementer, they know credentials issued and what type of credentials are issued -- same decision for error messages, might want to make the same call here.

The group noted that we probably don't want to define query parameters here and leave it up to implementers to provide that type of interface if they'd like... with possibly warning them that query parameters are typically used for simple search patterns and start to fail when complex search queries are needed.

On the currently drafted api spec, the GET /credentials endpoint lies exclusively on the holder component, however it seemed taken for granted 2 weeks ago that it belongs on the issuer component. When was this change discussed/introduced? Why was it originally planned for a holder endpoint and now the endpoint was discussed as not being part of a holder service?

@jandrieu noted that we haven't teased out what the holder coordinator and holder service do -- usually we call it a "wallet", we haven't set the boundaries well yet. We haven't teased out nuances on these things yet. Perhaps issuer has that endpoint for holder coordinator to display for current user?

An important functionality of a holder is to display the credential it currently owns to its user. Why would this not be reflected through the vc-api? I understand the use case of storing issued credential from an issuer for auditing purposes, however this was discussed as optional and based on business' requirements.

@PatStLouis noted, for mobile wallet use case, same way as issuer service has a way to access credential, this should definitely be part of a holder, they need a function to display credential, holder doesn't need API to do that? Don't understand how that would work.

The group agreed that a Holder Service should have a GET /credentials endpoint.

[msporny]

On the 2023-02-21 call the group decided to raise a PR to assign endpoints to components and expected callers with the caveat that we're not going to do that for the /exchanges/ endpoints nor the coordinator endpoints. The group will discuss both exchanges and coordinators over the next couple of weeks before assigning endpoints to those components.

[msporny]

The group discussed this issue again on 2023-07-25:

We currently have these endpoints (first part of path identifies service):

/exchangers - POST to create new exchanger /exchangers/<exchangerId> - GET to get configuration of exchanger /exchangers/<exchangerId>/exchanges - POST to create new exchange based on POST data /exchangers/<exchangerId>/exchanges/<exchangeId> - POST to participate in an exchange

Exchangers provide templates for flows that users will be taken through "factory for creating exchanges" that all take on the same shape. Will require specific variables and specific inputs from specific users (factory that pumps out exchanges that are specific interactions that are taken by users).

Exchange is an instance of a specific flow, instantiated and initialized for particular exchange, exchange is flow that goes through multiple steps that user using a client would make POSTs to exchange endpoint to complete some flow for specific interaction. Each flow has steps.

@jandrieu asked if an exchange, once it's created, has multiple templates? @dlongley noted "yes, it can have multiple templates if you are issuing multiple credentials throughout a given exchange. If you want to issue 10 different credentials in a flow, you would have 10 different templates. @jandrieu noted a term that has multiple things -- exchanger is both a component and thing that has specific templates. @dmitrizagidulin wondered how this interplays w/ notion of instance... is this a special case? @dlongley noted concerns about "issuers", "issuer instances", and sometimes we mean same thing, sometimes we mean different things. Sometimes "issuer" means "component", or "role" or "instance". What we're talking here is an "exchanger instance", with specific config, specific templates, etc.

@jandrieu noted that we should never talk about "issuer" by itself... we have issuer coordinators, issuer services, we should use terms for software components, that might clean up some of our discussion. @dlongley agreed, we should definitely do that in the spec text. We use "issuer instances", "verifier instances", and "exchanger instances", we should use those terms.

BIKESHEDDING HAPPENED BELOW:

DECISION: "Exchanger" Component should be called "Exchanger Service".

Seems like no one has a lot of love for the word "Exchanger". The group put forward "Exchange Factory", "Exchange Initiator", "Facilitator",

(Conductor, Maestro), Coordinator, Concierge, Mediator, Squire, "Exchange Instantiator"

Things that might be problematic: "Transfer",

Things to avoid: "Transaction", "Flow", "Workflow"

Initiator is person triggering the creation of an Exchange. Instantiator the exchange. (was Exchanger instance) Execute the exchange.

END OF BIKESHEDDING

1. Administrator would create an "Instantiator Instance". Represents some business rules and defines one of the possible flows that users can go through. This can happen way before a user would show up.
2. Administrator gives access to Coordinators to use an Instantiator Instance.
3. The end user requests the initiation of an Exchange from a Coordinator.
4. Coordinators would use an "Instantiator Instance" to instantiate an "Exchange".
5. The Exchange is executed by the end user.

No consensus yet, but feels close to consensus.

[brianorwhatever]

Unfortunately I can't make the call today but am starting to feel strongly against the "Instantiator" wordage.. I think I prefer "Facilitator"

[msporny]

"Initializer" was also suggested a week ago.

[msporny]

The group discussed this on the 2023-08-08 telecon:

@kezike noted he's been thinking about this and the word "initiate" feels close to "instantiate". Possibly call this an "Exchange Creator"... and think about "Activator" to activate the exchange. Note going from dormant to active state. @dmitrizagidulin and @jandrieu @PatStLouis noted that "creator" sounded good.

@PatStLouis asked if "create" was used for "presentations". @dlongley noted that at this point, whatever we use, there needs to be a prefix. The "action" word is too vague w/o that. @PatStLouis asked if it's paired w/ an endpoint, @dlongley noted that it is. @jandrieu noted that there are "three" things we're trying to identify -- "Exchange creator" is an instance... how do you create the instance?

Other things we discussed: exchange-flows, coordinator-flows, flows, interactions, routine, procedure, process, recipe, order, sequence, and exchange-templates

1. Administrator goes to the "Workflow Service" to create an "Workflow Instance". The workflow instance represents some business rules and defines one of the possible flows that users can go through. This can happen way before a user would show up.
2. Administrator gives access to Coordinators to use an Workflow Instance.
3. The end user requests the initiation of an Exchange from a Coordinator.
4. Coordinators would use an "Workflow Instance" to instantiate an "Exchange".

The Exchange is executed by the end user.

(This is on the "Workflow Service", not on other components):

/workflows - POST to create new flow /workflows/<flowId> - GET to get configuration of flow /workflows/<flowId>/exchanges - POST to create new exchange based on POST data /workflows/<flowId>/exchanges/<exchangeId> - POST to participate in an exchange

^^ This is what the group got to on that day, but further discussion is needed to make a final decision for a PR.

[msporny]

The group discussed this on the 2023-08-15 and the 2023-08-22 telecon:

@PatStLouis noted that we need to check with the Traceability folks. @jandrieu noted that, having thought about it, the concept still feels coherent. @dlongley noted that we might want to change flowId to workflowId. @PatStLouis noted that the idea grew on him, he liked it... wasn't sure last time, but makes sense now. @brianorwhatever noted that he liked it, thought it was good. @TallTed felt general concurrence that the direction was good. @bigbluehat noted that he thought the direction was good.

@PatStLouis asked if we need a GET /workflows call, @dlongley noted that we don't need to standardize that at present... clients just know the endpoints because administrators create them and configure/send the information to clients. @jandrieu noted that coordinators set up workflows for themselves (not across coordinators). @dlongley noted that an administrator creates workflows and gives those endpoints to coordinators to create those exchanges... only create workflows on systems that they control. @dlongley noted that we might need one more endpoint at the end, POST to use exchange, need an authorized endpoint to get current state of exchange.

The group felt that the following made sense. There would be a "Workflow Service". A particular "exchange" follows a "workflow". The following endpoints would be exposed for workflow services:

/workflows - POST to create new workflow

• Components: Workflow Service
• Expected callers: Administrators

/workflows/<workflowId> - GET to get configuration of workflow

• Components: Workflow Service
• Expected callers: Administrators

/workflows/<workflowId>/exchanges - POST to create new exchange based on POST data

• Components: Workflow Service
• Expected callers: Coordinators

/workflows/<workflowId>/exchanges/<exchangeId> - POST to participate in an exchange (does not necessarily need authz)

• Components: Workflow Service
• Expected callers: Anyone

/workflows/<workflowId>/exchanges/<exchangeId> - GET to get current state of exchange

• Components: Workflow Service
• Expected callers: Coordinators

(Ensure that text is added to the specification that clarifies that all coordinators can choose to proxy requests through to any Service they use).

[dmitrizagidulin]

+1, I like "workflows"!