Skip to content

Add /protocols endpoint to specific exchanges. #489

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add /protocols endpoint to specific exchanges. #489

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions exchanges.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,36 @@ paths:
description: Not Authorized
"500":
description: Internal Error
/workflows/{localWorkflowId}/exchanges/{localExchangeId}/protocols:
get:
summary: Gets the supported protocols for interacting with a specific exchange.
tags:
- Exchanges
security:
- networkAuth: []
- oAuth2: []
- zCap: []
operationId: getSupportedProtocolsConfiguration
description: Gets the supported protocols for interacting with a specific exchange.
x-expectedCaller:
- Verification Coordinator
- Holder Coordinator
parameters:
- $ref: "./components/parameters/path/LocalWorkflowId.yml"
- $ref: "./components/parameters/path/LocalExchangeId.yml"
responses:
"200":
description: Protocols understood by the exchange.
content:
application/json:
schema:
$ref: "#/components/schemas/GetExchangeProtocolsResponse"
"400":
description: Invalid input
"401":
description: Not Authorized
"500":
description: Internal Error
components:
securitySchemes:
$ref: "./components/SecuritySchemes.yml#/components/securitySchemes"
Expand Down Expand Up @@ -305,6 +335,27 @@ components:
redirectUrl:
type: string
description: The URL the exchange wishes to redirect the client to.
GetExchangeProtocolsResponse:
type: object
additionalProperties: false
description: Object containing information about the protocols that can be used to perform a specific exchange.
properties:
protocols:
type: object
description: An object containing one or more protocols that can be used to perform the specific exchange.
properties:
interact:
type: string
description: A URL that can be used during human-in-the-loop exchange flows.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs a better description, @dlongley. I'm at a loss as to what to write.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that we've defined the interact URL, we should just point to that section in the spec and / or reuse language from it. The value for interact is an interaction URL: https://w3c-ccg.github.io/vc-api/#interaction-url-format

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not arguing against @dlongley's suggestion, but this would be better than what's here.

Suggested change
description: A URL that can be used during human-in-the-loop exchange flows.
description: A URL that can be used during exchange flows with a human in the loop.

vcapi:
type: string
description: The URL to use when initiating a VC API exchange.
OID4VP:
type: string
description: The URL to use when initiating an OID4VP presentation.
OID4VCI:
type: string
description: The URL to use when initiating an OID4VCI issuance.
GetExchangeResponse:
type: object
additionalProperties: false
Expand Down
10 changes: 10 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1289,6 +1289,7 @@ <h4>Get Workflow Configuration</h4>
endpoint. This impacts the lifetime of challenges associated with such an exchange: if a
challenge is bound to an exchange, that challenge ceases to be valid at the date referenced by the `expires` property of the exchange.
</p>

<section>
<h4>Create Exchange</h4>
<p>
Expand All @@ -1298,6 +1299,15 @@ <h4>Create Exchange</h4>
data-api-endpoint="post /workflows/{localWorkflowId}/exchanges"></div>
</section>

<section>
<h4>Get Exchange Protocols</h4>
<p>
</p>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we need to explain how interact is supposed to work in this section?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or link to the interaction section? This section should say that the returned object lists all of the protocols supported by the exchange -- and that an implementation may implement an interaction URL handler by proxying/internally fetching this endpoint and returning its result to the caller.

We could use a mermaid style flowchart here to show an interaction URL being retrieved from a coordinator that internally looks up the associated exchange and fetches <exchangeId>/protocols and returns it to the caller. We can then explain that this allows the coordinator to delegate to an exchange service whereby the caller (client, e.g., digital wallet) can still use their trust in the coordinator origin -- as it serves (passes through) the protocols object.

<div class="api-detail"
data-api-endpoint="get /workflows/{localWorkflowId}/exchanges/{localExchangeId}/protocols"></div>
</section>

<section>
<h4>Participate in an Exchange</h4>
<p>
Expand Down