msporny
commented
1 year ago The group discussed this on 2022-10-18 related to the JFF Plugfest. @dlongley started off by noting that we had decided to ensure future proofing of top-level objects in the API, but failed to do that in the VC API Exchanges endpoint, which looks like it takes a raw presentation at the moment (which isn't aligned w/ the previous decisions we've made). The issue can be seen here in the current spec:
The issue is about updating the examples (and the OAS files) to bring it in line w/ the issuer API. There is an example that uses HTTP PUT, which has broken semantics, the caller is trying to initiate an exchange, POST is a better semantic for that to allow what it needs to do. John Henderson asked to elaborate on broken semantics. @dlongley provided the following:
https://w3c-ccg.github.io/vc-api/#continue-exchange
The PUT semantic is to put a resource at a location for retrieval later. Instead, what's being sent is a VP, which isn't being stored, you're exchanging the presentation for another presentation that has credentials in it or a VPR which has more data. You're not giving the server a presentation that it's going to hold on to forever. You're exchanging it for something else. @PatStLouis noted that we talk about VPs, and asked about what stage a request is made for a presentation, when are the constraints sent? @dlongley noted that when an exchange is initiated, an exchange URL is provided, you post empty body to exchange URL and in response you get back either a VP w/ VCs you're looking for OR you get back a Verifiable Presentation Request from the server, which is looking for more information. When you respond to the interact endpoint in VPR, you get credentials back (or another VPR). @dlongley noted that VPR means Verifiable Presentation Request. Also, if you get a VPR over something like CHAPI, which contains an interact field with VPR that says where to respond to.
@PatStLouis noted that this is different from the "agent connection" concept in Aries. There is also OOB communications, which seems to be the approach here -- communication not bound to pre-existing connections. @dlongley noted that you might start the interaction from a website and the site is able to generate a VPR to pass to you via CHAPI, choose a wallet, and respond to VPR. There are other use cases where you get an exchange endpoint through another mechanism, and you can hit the endpoint and it will tell you what you need to proceed further.
@dmitrizagidulin noted that he doesn't expect a lot of JFF implementers to go the VC API Exchanges route, because it's slightly more complicated than just issue, but would love to hear from people that are.
Next steps are to raise a PR that fixes the exchanges endpoints to ensure that when a Verifiable Presentation is sent or returned that it is contained in a verifiablePresentation property.
dlongley
The exchanges API examples show endpoints accepting raw VPs instead of
{"verifiablePresentation": <vp>}. We decided elsewhere that we should use top-level properties to ensure we are future-proofed against additional properties that may need to be added. Additionally, the examples show using the HTTPPUTmethod where the semantics aren't quite right andPOSTshould be used instead.We should update the spec to make sure that payloads (in requests or in responses) use top-level JSON properties not raw VP/VCs in the exchanges API.