The W3C Credentials Community Group

Verifiable Claims and Digital Verification

Go Back

Verifiable Credentials HTTP API Telecon

Minutes for 2021-05-06

<cel> scribe+
<juan_caballero_(dif/spherity)> next week i can scribe!
Charles E. Lehner is scribing.
<juan_caballero_(dif/spherity)> i'm not at a good desk but at least i'm not driving this week
Manu Sporny: Welcome
<juan_caballero_(dif/spherity)> i can screenshare the google doc of use cases, or joe or eric can, all good
Manu Sporny: ... This ian intellectually property protected call.
Manu Sporny: Everything you put in to the group you are okay with us using.
... If you haven't done the release, please refrain from contributing anything substantive.
... We use the queue. You can q+ to add yourself to the queue.
Manu Sporny: We are trying to establish a broader understanding of the VC HTTP API work.
... Trying to focus on concrete things we can document, to get everyone on the same page on what the API is about.
... There has been fruitful discussion on mailing list - we will not rehash.
... We're here today to look at concrete proposals people have put forwards - concrete use cases we can analyze.
... Trying to move faster to document these things and share knowledge.
... Questions, concerns?

Topic: Specification Structure Proposals

Manu Sporny: All the proposals that anyone has ever raised ^ so we can track everything.
... There have been new issues raised around some of these proposals.
... 3 Proposals on table: 1 is to have three separate specifications.
... That one got a lot of -1s on the last call.
Adrian Gropper: ... I kindof object to the introduction of the current status quo into the process... I can say why...
Manu Sporny: DRAFT PROPOSAL: Create a VC HTTP API specification in ReSpec format so that we can document and iterate on the current client-server HTTP protocol for the purposes of issuing a Verifiable Credential.
Adrian Gropper: In the conversation we had in the thread, there was a desire to parallelize as much as possible - not to block on the use cases document while we start to work on a potential document specification or whatever.
... By not introducing the current client-server framework, we can unblock, and introduce this parallelism, by not making assumptions. That is my proposal
Manu Sporny: Can you put forward a concrete proposal?
Adrian Gropper: Yes
Adrian Gropper: DRAFT PROPOSAL: Create a VC HTTP API specification for HTTP protocol for the purposes of issuing a Verifiable Credential.
Orie Steele: While I agree with Adrian's intention... If the goal is to talk about scope for moving credentials between issuers, holders, and verifiers in general, then I do think it is a mistake to start with a client-server architecture.
... However, this spec is ... client-server, and I find it ... a mistake to ... go back to the drawing board.
<tallted_//_ted_thibodeau_(he/him)_(openlink_softwa> "We've all" is an overstatement, relative to current audience.
... I'm willing to work on those issues, but asking to expand to non-HTTP protocols will result in a -1 from myself.
Jim_StClair: ... I support Adrian with his use case, Health care
<orie> TallTed, folks on this call have been working on this item for a long time... I recognize there are new folks here... but we starting from scratch seems very dismissive of work that has already happened... we need to find some middle ground that isn't back to a blank slate.
Mike Prorock: Clarification: create a vc-http-api specification ... for purposes of issuing a verifiable credential... I'm just not sure the intent. It seems limited just to issuing. Seems odd to me compared to some of the other proposals we have saying we want a ReSpec specification for HTTP around verifiable credentials.
... I just need some clarity on why it says issuing a credential.
Manu Sporny: The suggestion is to start with issuing and then expand scope later on when it gets obvious.
... Just to start documenting the issuer API
Manu Sporny: DRAFT PROPOSAL: Create a VC HTTP API specification for HTTP protocol for the purposes of issuing a Verifiable Credential (do not use the OAS file as inputs to the specification).
Mike Prorock: That's helpful.
<orie> TallTed I agree with your asssertion that this has not been handled in the open correctly though.
Adrian Gropper: I'm concerned ... to move to delegation. Also the conversation of the "narrow waist" of the API stack in general, that we're working on at W3C and DIF - whether it represents a messaging protocol like DIDComm, or an authorization protocol, or both.
... I took ReSpec out of my proposal ... just didn't understand.
Manu Sporny: I've rewritten your proposal... Your proposal says we would not use the OS files... that's what you intend?
Adrian Gropper: I didn't mention it one way or the other
Adrian Gropper: Sure
PROPOSAL: Create a VC HTTP API specification for HTTP protocol for the purposes of issuing a Verifiable Credential (do not use the OAS file as inputs to the specification).
Manu Sporny: -1
Mike Prorock: -1
<juan_caballero_(dif/spherity)> the OAS (openAPI/Swagger doc) files are... the last year's work?
Orie Steele: -1
Mahmoud Alkhraishi: -1
Adrian Gropper: +1
Charles E. Lehner: +0
Joe Andrieu: -1
Kyle Den Hartog: -1
Manu Sporny: Adrian, I hope you'll see that proposal won't pass. Do you want to run your other proposal, assuming we take the OAS files, use them as input into the specification?
Adrian Gropper: No, I haven't looked at what that would imply. I would then move to wanting to work on the use cases first, before working on the document.
Manu Sporny: Just a note: those OAS files have existed for 15 months in the public. The group working on them, for while. That you haven't read them is unfortunate, but we can't allow not keeping up with the work to stop making decisions.
<orie> well.... in fairness to folks, those files are the only thing you can read.... about the work item.
... I don't think that's a reason to stop all proposals on the specification.
... There has been discussion on this on the Mailing List.
<orie> we don't have anything except those files and the readme...really.
... We have two proposals: one is to do ...
... The other is yours that says just start with Issuer.
... Which would you prefer to run?
Adrian Gropper: I feel like I've made my case in the thread; I'm not sure it serves for me to revisit the issues discussed in the thread.
... No reason for me to repeat what was discussed
Manu Sporny: The discussion around this item is here:
Mike Prorock: +1 Orie - that is why i would like to get on to proposal's 4 and 5 on the wiki - e.g. let us get a respec doc in place, and break the OAS into functional components
Manu Sporny: Do you have a preference on which one for us to run?
Adrian Gropper: I have an objection to your language on my participation style, and being railroaded...
Adrian Gropper: If need to move to W3C, steering committee...
Manu Sporny: Does anyone think we are not considering agropper's input?
Ted Thibodeau: Not specifically about agropper's input, but feeling to me like a broken piece of process.
<orie> the work items has a commit history....
<orie> "we all" refers to contributors
... You referred to some files out for 15 months... I haven't looked at them. Some people on this call referred to "we all" or "all of us" - doesn't include me, Adrian, don't know how many others.
<orie> in that history.
... Commit history is immaterial. CCG is a branch of W3C efforts. yes, anyone can create a CG, but these are open and public. Work done on SVIP is not open/public, not part of CCG, to my knowledge.
<mprorock> why is commit history irrelevant if it is in the open and as a ccg work item repo
Manu Sporny: It has, to be clear. Work item created last January(?). Has been a work item for a year/
Ted Thibodeau: Well, part my fault for being sick and out of commission for ? months
<mahmoud_alkhraishi> I feel like we're losing the thread of what we're trying to do here
<mahmoud_alkhraishi> we're trying to make it more accessible
<mahmoud_alkhraishi> and explain what has been done
Manu Sporny: From a process perspective, the work item has existed. We understand people are new. We are trying to document stuff so people can understand.
... Primary thing trying to do is to document - start writing this stuff down.
Ted Thibodeau: What is it that is trying to be written down?
... The way it has been discussed in meetings I've been in, have not been limited to HTTP, API, and VCs. I have no hook on which to hang anything to consider it.
Orie Steele: I want to address the criticism directly. TallTed and Adrian are both correct that a GitHub history and group of contributors is a form of history that is not accessible to everyone.
... Heather has done a great job trying to address this. This work item predates...
... I think what Ted and Adrian are saying is that there is a style of contribution this API could have enjoyed, which would not have been git-oriented.
... We welcome that kind of contribution... We're having it right now, a conversation, not async over pull requests.
... We need to create space for non-git-oriented contribution.
... But need to acknowledge the work has been. A failing, but it is the case.
Adrian Gropper: Unfriendly tone is unnecessary - I'm not blocking the learnings and work - Just asking us to zero-base our documentation going forward.
<evan_tedesco> I didn't take it as unfriendly. Orie just talks like that haha.
... It is unfair as a process matter to interpret what I'm saying in that way. I'm doing the best I can to not block the process.
Mprocock: My perspective may be unique: I jumped in and VC-HTTP was already a thing. I had a need to exchange credentials, issue and verify them over a REST Web service.
... When I first looked at it, all that existed was an API spec with a swagger interface and no ...
... As a developer it was not ... approachable.
... My understanding of the proposals: there is a bunch of knowledge in people's heads that have been collaborating and committing on these - How can we document that in a specification file.
... I'm not getting a sense that Adrian you are trying to block, just ... trying to understand.
... My intention is for us to get to a point where we can say there is a need to do things with VCs ... and put a document in place.
... Multiple folks implementing... Get it on paper. Then adjust it, how can we make it better.
<dlongley> If we just gave the spec that some people want to write down a different title -- that reflects it as an "input document" -- would that unstick all this?
... How can we get this in a forward process, to the point where we are not repeating errors, falling into the trap that folks like Ted are rightfully calling out as serious issues on how this work has been done previously.
Ted Thibodeau: There is a need to transfer VCs and other related things over various protocols, including HTTP and REST-based stuff.
<dlongley> it could later be renamed to VC HTTP API as the official spec ... or not, but at least it would be written down.
... It would be better, in my opinion, to cover the general case, and have the specifics in HTTP as the "core exercise".
... Typically in specs... multiple things, one discussed as ... an example core ... way.
... But the de facto limitation to those things is problematic.
Manu Sporny: DRAFT PROPOSAL: Create a VC HTTP API specification in ReSpec format so that we can document and iterate on the current Open API Specification client-server HTTP protocol for the purposes of issuing a Verifiable Credential.
Manu Sporny: Thanks. Just a reminder, if we are starting here doesn't mean we are limited to here.
<mahmoud_alkhraishi> is this a single documetn?
<mprorock> @ted is the VC spec not that in some ways? e.g. protocol agnostic what are vc's and what can you do with them? and then the vc-http-api being how do you do those things over http
Manu Sporny: Proposal... Start with a specificaion that is only going to do VC HTTP issuing. Later we may expand scope into a specification.
... Mahmoud_Alkhraishi, yes, it's a single document.
PROPOSAL: Create a VC HTTP API specification in ReSpec format so that we can document and iterate on the current Open API Specification client-server HTTP protocol for the purposes of issuing a Verifiable Credential.
<bblfish> where is that OpenAPI spec?
Manu Sporny: +1
Mahmoud Alkhraishi: +1
Joe Andrieu: +1
Adrian Gropper: -1
Manu Sporny: We'll run the other one that does all three, after this
Aaron Coburn: +1
Mike Prorock: +0
Orie Steele: +1
<markus_sabadello> +0.5
Kyle Den Hartog: +0
<juan_caballero_(dif/spherity)> (wait i will retract my +1 because I'm not 100% clear on the "issuer first" timeline)
Manu Sporny: DRAFT PROPOSAL: Create 1 ReSpec specification based on the OAS files, in addition to separating the existing OAS files into modular components.
Mahmoud Alkhraishi: +1
Mike Prorock: +1
Manu Sporny: Any modifications folks would like to see here?
PROPOSAL: Create 1 ReSpec specification based on the OAS files, in addition to separating the existing OAS files into modular components.
Manu Sporny: +1
Mahmoud Alkhraishi: +1
Joe Andrieu: +1
Orie Steele: +1
Dave Longley: +1
Adrian Gropper: -1
Kyle Den Hartog: +0
<mprorock> can we mute @bengo
Aaron Coburn: +1
Markus Sabadello: +1
<bengo> Sry
Mike Prorock: Np :)
Manu Sporny: Seems to be getting more support, as far as I can tell
RESOLUTION: Create 1 ReSpec specification based on the OAS files, in addition to separating the existing OAS files into modular components.
Manu Sporny: We will create a ReSpec specification and move the OAS files into it. That doesn't mean everything is locked in and done and not changing. All content in the specification is up to debate - as is any CCG item. It hasn't gone to a working group or official recommendation.
<orie> wait you mean that get stores the version history and allows for non monotonic standards development?
... New folks, you will have time to read up on the OAS files, raise issues, PRs, etc.
Manu Sporny: Thanks everyone, I know that was difficult.
... Let's go to use cases. Folks have been wanting to figure out what the scope is for this work item. I thought we could look at the use case template and a couple of use cases.
... Specifically, looking at use cases that are clearly in scope, hopefully, and one that is probably not in scope.

Topic: Use Cases

Adrian Gropper: As we talk about the use cases, and I know I have only contributed informally, can someone explain why this API spec is concerned about persistence about the verifiable credential? Or is it just that I haven't read the OAS files.
<orie> on q to answer adrian, as best we can
<mike_varley> That is an excellent question agrropper!
... If we're talking about an API from the issuer perspective (vs. holder), why we are we talking about persistence?
Orie Steele: Excellent question. The first versions of this API did not discuss persistence. Most of the endpoints are stateless. They are basically an operation that happens. A result is returned, and no persistence...
... First violation is revocation lists. State needs to be updated. Tests are very limited. Those are the first set of endpoints that ask can I change the state of a credential... implies that they are stateful.
... Not documented super-well. The updateStatus endpoint. The only example in the spec that is in any way stateful or comprehends persistence.
Adrian Gropper: Does revocation imply persistence? From what I understand about it, there are many ways to do revocation. There may be one proposed which may be totally fine.
... But I don't see, from the perspective of the issuer, that they have to persist a particular credential, in order to revoke it.
<orie> hosted lists imply the issuer manages a persisted list on a web server.
Manu Sporny: There are some revocation use cases where the issuer must persist. For example, Revocation Status List 2021 assumes... a bit string... has to update that bit string.
... But that does not hold for all types of revocation, only a subset.
Adrian Gropper: In this case, it is an issuer persisting a copy of the credential they have issued, not anyone else.
Manu Sporny: In this case, yes.
<orie> that form of revocation is the only currently document form of revocation in the api.
<dlongley> i'd say -- it just depends on whether the holder is requesting revocation or the issuer wants to revoke independently.
Adrian Gropper: We don't have a use case for talking about the API that requires persistence - whether revocation is necessary or not...
Kyle Den Hartog: The case we've found most useful is when you are producing a registry.... The issuer is ... public credentials...
... being able to recognize someone has been a graduate of a particular university. The ability to go to the issuer and ask...
... Being able to use the issuer API, while at the same time publishing the fact that they've received that degreee. One use case we've found useful.
Mike Prorock: +1 Similar use cases with historical records of agricultural activities
<orie> ahh, i heard persistentence a question of if any of the http apis are stateful.
Joe Andrieu: ... Question about API... In order to have revocation, there needs to be persistence about the ... state. Doesn't mean the issuer needs to store the VC to store the fact that it's been revoked.
... Does the API not handle a refresh endpoint?
Manu Sporny: It does not - have not documented that use case yet.
Manu Sporny: Sharing screen. Template that can be filled out. I've added a couple use cases, and Alan Karp has added a number of use cases.
... I thought we'd take a look at these use cases. The idea and hope is that the rest of the people on this call will start adding use cases.
<kyle_den_hartog> Just realized I’ve not added that use case to this document. I’ll be sure to add it.
... Ones we've brought up today are not yet documented.
... Let's take a look - I've submitted a couple. Joe, thank you, went it and noted some are lacking in some areas.
... I tried to rewrite to meet things Joe said to do.
... Can we look through and get feedback... This one is a real use case... SVIP
... Other thing is one out of scope.
Manu Sporny: This use case is a digital permanent resident card use case.
... reading Get Digital Permanent Resident Card
... I also took a shot at doing a really simple flow diagram, so folks can understand where calls are made, where the APIs are.
<juan_caballero_(dif/spherity)> looks great to me!
... Joe, is that closer to what you were looking for? Juan, anyone else, thoughts?
<josh_mandel> Where / how is the "PIN" involved in this flow? An additional factor or the sole factor in the "Log in and..." step?
Joe Andrieu: Huge improvement. Part of what I hope to highlight to folks: when you get details of what an actual person is doing, it informs the work.
... This helps a lot compared to the simpler version before.
... All the items here I don't think will be hard to translate into real situations. They are all really good task-based use cases. Need to issue, revoke, present, etc.
... A great start.
Juan Caballero: I think this is a really good paragon. People who want to convert other use cases should feel free to use this pattern. As long as...
... I also think the term Industry-Standard API is doing a lot of work here.
... Part of the ambiguity here is: one basic intention thing that has been hard to align on is the "Industry-Standard API" part. That's what this is trying to provide.
... If there are multiple use cases / parties... This API is a neutral cross-vendor API, free of lock-in.
... Assumption of what use cases are based in is a little orthogonal. This is trying to arrive at a maximally neutral API where HTTP is appropriate for vendors to pass things back and forth.
... Any use case that has multiple vendors: good to emphasise the "Industry-standard" part.
Adrian Gropper: I think this is a beautiful example of my concerns of the process. In this nicely-described use case, we've introduced the idea that the permanent resident has not only all the credentials they need, but is also providing a DID associated with his digital wallet.
<orie> maybe we should run a proposal to support DIDs or not?
... If it is our express intent to introduce or bundle this fact (which we might not want to do for a covid credential) - that the subject has to meet certain requirements to receive the credential - like having a DID or DID wallet - then sure, it's a use case; I just don't know if it's useful to bundle these things together.
Joe Andrieu: Each of these use cases are simple illustrations of how we expect the technology to support solving real-world problems. They are not mandates that all use cases have these requirements. This particular flow is a real use case likely to be deployed.
... Different situations have different requirements.
... If you think it's important, let's get a use case in that doesn't have DIDs as a requirement.
<juan_caballero_(dif/spherity)> but does have multiple (interchangeable, competitive) vendors passing VCs between each otehr :D
Kyle Den Hartog: Would it be useful to document ... about usernames and passwords...
Adrian Gropper: No...
... If a government ... restricts ... a wallet... for example FIDO requiring ... token from manufacturer, then ... add to use case.
... It's a badly documented use case if we don't include the reason why the DID and DID wallet are there.
<orie> To be clear... there is no DID Wallet in these APIs
... If those are added, it's a beautiful use case.
Manu Sporny: This is an example of a use case that is real and more than likely will be accepted as in-scope.
... One I think we would agree is out of scope: "Obtain an Authorization". One issue is not a lot here.
... Obtaining an authorization to use one of these endpoints is more than likely going to happen through some other interaction/standard/flow.
... Using an authorization to make a call is in scope. But obtaining an authorization is probably out of scope.
<mprorock> i have a hard stop in 5
Juan Caballero: I was just going to ask if a longer version of a use case is already documented elsewhere in another CCG repo (such as SDS or something), is it bad form to link to longer forms of use cases?
... like why a use case vendors use DIDs
Ted Thibodeau: I saw a number of gaps and confusing points in the first use case. Is this doc staying, or going to GitHub?
<juan_caballero_(dif/spherity)> TallTeditor!
Manu Sporny: It is going to stay as a Google doc for the forseeable future.
... We decided last week...
Ted Thibodeau: I see obtaining an authorization... as in scope.
Kyle Den Hartog: To explain the difference betwen use and obtain. Obtain brings the API into a level where it has to be used as a protocol of sorts. Whereas Use allows it to stay in the backend.
... That is why I think out of scope. One is elevating the architecture... may make messier.
<orie> who can call the issuer api.... ? anybody? like it is today?
Kyle Den Hartog: +1 Joe
Joe Andrieu: I think a good example about though well-intended, the lack of specificity about what authorization is for... If for some other trust domain, like getting into an apartment building, that starts to get weird. But if talking about authorization about the system itself - which can issue, etc. - then I think both need to be there.
<orie> i think its a question of how are the http api's secured.... on the public internet.
Manu Sporny: Next steps... We have a use cases document. Please fill out the use cases you feel are important.
... This will drive the scoping discussion.
... In parallel, we will start the ReSpec document - without any coontent
Orie Steele: We failed to review these PRs:
... Next week, we will talk about any use cases added since now, then talk about the structure of ... the ReSpec document.
... Thanks everyone
<juan_caballero_(dif/spherity)> thanks all
<jim_stclair> well done
<mike_varley> thanks!