Should workflow `id`s and `name`s be provided in the URL or POST body?

[msporny]

When workflows are identified by name or by id, the current spec specifies them in the URL. There are upsides and downsides to doing this.

Initially, I wrote the spec text up to define workflows as a concrete URL because when I asked the question to the group, @OR13 wanted it to be defined in this way rather than it be a "pattern" that can be used. That is, I'd rather /not/ define ONE endpoint to start all workflows or accept all presentations. Developers should be free to choose any endpoint to act in this way. I'm not going to argue that here, though. I just needed to get this down in a way that @OR13 felt like we could have a discussion over it. I think focusing on the name/structure of the URL is probably too deep in the weeds at this point of the analysis.

There is a debate to be had about whether or not {id} belongs in the URL or if it belongs in a POST body. One argument to allow it in the URL is for when browsers are invoked by native apps, where it is not possible to perform a POST.

[OR13]

That is, I'd rather /not/ define ONE endpoint to start all workflows or accept all presentations.

We have already defined AT LEAST one endpoint that accomplishes this.... I am not suggesting that it is the only one.

[OR13]

One argument to allow it in the URL is for when browsers are invoked by native apps, where it is not possible to perform a POST.

yes, an excellent point.. perhaps the entire VP request spec should be translated into query string arguements to facilitate this use case?

[msporny]

yes, an excellent point.. perhaps the entire VP request spec should be translated into query string arguements to facilitate this use case?

I don't know if you're trolling me or not... :)

Given that Apple is starting to strip query parameters off of URLs in the name of tracking protection and privacy, this approach probably won't work long term.

We could specify that the entire VPR can be base64url encoded and added with a "?vpr=" option, but again, would rather wait for someone to have an explicit need for that use case instead of presuming it exists. To be clear, there is nothing in the spec that prevents this from being done today. At present, we can't think of a single use case that is Native App -> Browser initiated that can't encode what it needs to in the URL itself (without having to encode the entire VPR).

[OR13]

I am not trolling.

If browser invocation is a feature, then the endpoints should be defined to support it.

They would need to be defined here... if they are to be supported here.

If the endpoints are not defined here, I expect they will be defined elsewhere.

[msporny]

If browser invocation is a feature, then the endpoints should be defined to support it.

Technically, it's a feature that /might/ be for VPR, so it should probably be defined there. The only use case for it at this point is the MediatedBrowserPresentationService2021 defined in: https://w3c-ccg.github.io/vp-request-spec/#mediated-presentation

I expect the VC API spec should probably say something to the effect of "you might get query parameters in, and if those are important to your workflow, you should pay attention to them." We should be careful to not tightly bind VC API to VPR, just as an appropriate layering principle... though I do realize that we're specifying schemas that are for VPR (we shouldn't preclude other schemas at these endpoints).

I'm not purporting to have a plan here, just some design considerations that we should have in the back of our heads as we go through this next round of design and interop testing.

[OR13]

We should be careful to not tightly bind VC API to VPR, just as an appropriate layering principle.

I don't agree with this.

We should support 1 thing well before attempting to support ANY generality.

If you think this is a VPR issue, perhaps you should be defining workflows in VPR, and not in this work item?

[msporny]

We should support 1 thing well before attempting to support ANY generality.

If by "thing" you mean "the mechanism that we use to execute on a use case", I agree.

If you think this is a VPR issue, perhaps you should be defining workflows in VPR, and not in this work item?

I don't know how to do that given that workflows require an HTTP API and protocol to work.

To be clear, I'm all on board with getting "VC API + VPR" working for as many use cases as we can and putting our focus there. In the meantime, I personally find it useful (from a design perspective) to understand where the extensibility points are (so if we're wrong about VPR or VC API, it's possible to jump to a different protocol that /did/ get some use case right, where we might have failed to do so). Yes, it leads to variability, which is frustrating to implementers, but it also de-risks decisions we're making today and enables innovation on those extension points in the future. Tightly coupling a bunch of technologies together just so you can do an end-to-end workflow, while allowing you to make rapid progress in the first couple of years, leads to ossification over time (and, typically, the failure of the technology in time).

All that said, I'm struggling to understand your comment's relevance to the issue at hand and so we should probably go back to discussing concrete things related to the issue.

[agropper]

If I’m not mistaken, this is a first-class authorization issue form my human agency / ability to delegate perspective. The domain to which a request or query is made /must not/ presume to be the same as the domain that is authorized to release the (VC or VP) resource.

• Adrian

On Tue, Feb 1, 2022 at 10:56 AM Manu Sporny @.***> wrote:

We should support 1 thing well before attempting to support ANY generality.

If by "thing" you mean "the mechanism that we use to execute on a use case", I agree.

If you think this is a VPR issue, perhaps you should be defining workflows in VPR, and not in this work item?

I don't know how to do that given that workflows require an HTTP API and protocol to work.

To be clear, I'm all on board with getting "VC API + VPR" working for as many use cases as we can and putting our focus there. In the meantime, I personally find it useful (from a design perspective) to understand where the extensibility points are (so if we're wrong about VPR or VC API, it's possible to jump to a different protocol that /did/ get some use case right, where we might have failed to do so). Yes, it leads to variability, which is frustrating to implementers, but it also de-risks decisions we're making today and enables innovation on those extension points in the future. Tightly coupling a bunch of technologies together just so you can do an end-to-end workflow, while allowing you to make rapid progress in the first couple of years, leads to ossification over time (and, typically, the failure of the technology in time).

All that said, I'm struggling to understand your comment's relevance to the issue at hand and so we should probably go back to discussing concrete things related to the issue.

— Reply to this email directly, view it on GitHub https://github.com/w3c-ccg/vc-api/issues/256#issuecomment-1026998800, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABB4YIKBZMNS3SZWNU4SHTUY77DHANCNFSM5NEWMTKQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you are subscribed to this thread.Message ID: @.***>

[msporny]

The domain to which a request or query is made /must not/ presume to be the same as the domain that is authorized to release the (VC or VP) resource.

This issue nor endpoint makes no such presumption. In fact, quite the opposite, if Verifiable Presentation Request is used, the interact mechanism (which is quite similar to what GNAP does), allows the release of the VC or VP to happen at a different domain.

[agropper]

Ok, but then is there a reason not to use GNAP? The reason is that a person-centric design would have all requests go to the same authorization server regardless of the resource domain (government vs. payment vs. education vs. health records, etc...)?

On Tuesday, February 1, 2022, Manu Sporny @.***> wrote:

The domain to which a request or query is made /must not/ presume to be the same as the domain that is authorized to release the (VC or VP) resource.

This issue nor endpoint makes no such presumption. In fact, quite the opposite, if Verifiable Presentation Request is used, the interact mechanism (which is quite similar to what GNAP does), allows the release of the VC or VP to happen at a different domain.

— Reply to this email directly, view it on GitHub https://github.com/w3c-ccg/vc-api/issues/256#issuecomment-1027447844, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABB4YLAKX4PFYARIWV564DUZB4BFANCNFSM5NEWMTKQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you commented.Message ID: @.***>

[msporny]

Ok, but then is there a reason not to use GNAP?

Yes, because 1) it has no bearing on this issue, please don't hijack issues to talk about GNAP, and 2) none of the implementers want to implement at present, and until there is an implementer that wants to apply GNAP to the VC API, there is no discussion to be had.

[agropper]

https://xkcd.com/927/

On Tuesday, February 1, 2022, Manu Sporny @.***> wrote:

Ok, but then is there a reason not to use GNAP?

Yes, because none of the implementers want to implement at present, and until there is an implementer that wants to apply GNAP to the VC API, there is no discussion to be had.

— Reply to this email directly, view it on GitHub https://github.com/w3c-ccg/vc-api/issues/256#issuecomment-1027474711, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABB4YOMNVQQ46PN6AUETNTUZB7NRANCNFSM5NEWMTKQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you commented.Message ID: @.***>

[mprorock]

Chair hat on: @agropper after numerous complaints in from the community, and from contributing members of this work item regarding blocking of forward progress on this work item I would respectfully request that you disengage from this work item unless it is in a constructive fashion.

Repeatedly bringing up GNAP where it is not applicable is actively harmful to the work item, and that has been stated clearly to you multiple times.

[mprorock]

Back to normal implementer role: Typically in restful APIs you want to permit where known the ID to the resource in both URI and payload (if payload is appropriate for that type of method)

If you haven't taken a look at the REST guidelines lately i would recommend a revist, since several things have been clarified lately in revisions

Some helpful discussion is here. Basically if ID is known, such as in a PUT you permit it in the path, if POST, to create a new item, you may still have an ID in the path, if for instance you are creating an object of a specific type identified by that ID

[OR13]

@msporny The issue title is regarding an HTTP endpoint.

My comment is that if that endpoint is mentioned here, it should be defined here.

I can't effectively contribute to work that is split across so many work items.

I am trying to drive the VC-API towards a concrete defintion for HTTP based flows, I think we have rough consensus regarding support for:

• VP Request Spec
• Revocation / Status Lists Spec

Workflows are stuck in some weird limbo world where they are not defined sufficiently for interop anywhere... they should be removed if we can't define them sufficiently in this item... that means defining endpoints related to them in OAS3.0 according to the guide mentioned above.

[msporny]

My comment is that if that endpoint is mentioned here, it should be defined here.

Sure, and we plan to -- the initial PR didn't lock the format down, there is agreement to do so, but conversations on exactly how are continuing in the VC API work item meetings.

Workflows are stuck in some weird limbo world where they are not defined sufficiently for interop anywhere

There was agreement between Mesur.io, Mavennet, and Digital Bazaar to do a PR to merge the two workflow calls and the two presentation exchange calls in a way that's backwards compatible with what Traceability is doing, but in a way that supports the credential refresh flows. I'm working on those PRs this week.

I'll point to the minutes of the discussion when I get them cleaned up and published.

[OR13]

@msporny to be clear, I am 100% ok merging PRs that are not perfect, and following up with smaller PRs especially for CG Drafts... I am trying to provide feedback on the shape those smaller PRs seem to need to take, namely they need to define OAS3.0 params properly.

[msporny]

@msporny to be clear, I am 100% ok merging PRs that are not perfect, and following up with smaller PRs especially for CG Drafts...

Thank you for clarifying, I was concerned that we were asking for perfection in the first PR that's merged and would stop allowing features to improve (rapidly) after they're introduced.

I am trying to provide feedback on the shape those smaller PRs seem to need to take, namely they need to define OAS3.0 params properly.

Yep, agreed. Missing definitions are either 1) oversights/mistakes, or 2) done because I don't know what the group wants yet and I don't want to start with something that immediately presses someone's "I hate this" trigger.

As an example -- @mprorock wants these id values to be UUIDs. I think DB wants a bit more flexibility than that... possibly multibase-base58btc encoded 32-bit unsigned integers. So, should we allow both, either or, are there other forms to these values that people want? Should I just put in a regex for UUID and/or multibase-base58btc encoded integers? Is @OR13 just going to object to having IDs in the URL? These are the unanswered questions I have flying around in my head, so defining the params properly in OAS feels premature before I know what folks want in the spec. I will get to doing that as soon as we get some consensus on the questions above.

[OR13]

I would need to a see a PR that defined things to object to it.

You can generally count on me to prefer UUID over custom base58btc encodings.

[TallTed]

[@OR13] I am 100% ok merging PRs that are not perfect, and following up with smaller PRs especially for CG Drafts

I generally agree with you, with one addition: merging such imperfect PRs should either be simultaneous with creation of issues reflecting the known imperfections, such that the mentioned smaller PRs are more likely to be created and merged later and/or add text noting the imperfection directly to the doc (using class=note, class=issue, or similar).

[@msporny] These are the unanswered questions I have flying around in my head

I strongly suggest recording such unanswered questions as issues, even if they're badly framed to start. This would significantly reduce the likelihood that they might not be addressed in the published document, as well as make it plain to others that such questions exist — as those others might otherwise think that they are already answered in some way that they like, potentially leading them to overlook them when raised and/or answered differently later in the process, or don't like, leading to objections that would be avoided by having flagged, even if not answered, those questions.

[agropper]

@Chairs,

I will certainly abide by your requests but I'm confused by your statement that my comment was not applicable. I took Manu's reply to mean that respectfully pointing to GNAP as an alternate standards-track approach was applicable but not necessarily a path the current implementers are interest in.

I've already agreed to disengage from CCG for various reasons because the chairs felt my contribution was not constructive. If the group is thinks my contribution on authorization-related aspects of VC-API are not constructive, then I will disengage here as well.

• Adrian

On Wednesday, February 2, 2022, Mike Prorock @.***> wrote:

Chair hat on: @agropper https://github.com/agropper after numerous complaints in from the community, and from contributing members of this work item regarding blocking of forward progress on this work item I would respectfully request that you disengage from this work item unless it is in a constructive fashion.

Repeatedly bringing up GNAP where it is not applicable is actively harmful to the work item, and that has been stated clearly to you multiple times.

— Reply to this email directly, view it on GitHub https://github.com/w3c-ccg/vc-api/issues/256#issuecomment-1028020528, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABB4YKDJWT2JP53Y4YE4U3UZFAPXANCNFSM5NEWMTKQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you were mentioned.Message ID: @.***>

[mprorock]

I've already agreed to disengage from CCG for various reasons because the chairs felt my contribution was not constructive. If the group is thinks my contribution on authorization-related aspects of VC-API are not constructive, then I will disengage here as well.

Adrian - The VC-API is a CCG Work Item and is part of CCG - Please be on the lookout for an email from @vsnt or myself

[msporny]

@TallTed wrote:

I strongly suggest recording such unanswered questions as issues, even if they're badly framed to start.

I just did, in this issue: https://github.com/w3c-ccg/vc-api/issues/256#issuecomment-1028049331 :)

As for creating a separate issue for all of those questions, that asks me to do a lot of work that I'm not convinced is worth my time. I've asked the questions above, the people I need to hear from are in this thread already (@mprorock @OR13 and @mkhraisha), if they can answer the questions, we're done and I can apply the changes they want (as long as we have consensus).

[mprorock]

@msporny want me to take a stab at a PR to the OAS? That way @OR13 has some code to look at

[msporny]

@msporny want me to take a stab at a PR to the OAS? That way @OR13 has some code to look at

I'm currently doing the merge between Workflows and Exchange/Presentation Available, etc...

@mprorock if you could propose how we change all the endpoints to meet the RESTful design principles you were talking about (shift to HTTP verbs on collections, etc.), that would speed things along. I'm not doing that work right now and it's something I'd rather you do anyway.

[OR13]

URL parameters should have defined types.

You should make sure those parameter types cover all the cases you want to support, and handle safe characters, etc...

Also provide examples.

[mkhraisha]

probably should also have an endpoint where you can fetch what types your implementation supports

[msporny]

The group discussed this on the 2022-02-08 telecon. The group is open to placing ids and names in a URL, but require PRs to explore the specific use of id or name for a particular use case. It is expected that any path parameters need to be very clearly defined with generous examples in the PRs.