search

w3c-ccg / community

COMMUNITY: W3C Credentials Community Group Community Repo
https://w3c-ccg.github.io/community
Other
41 stars 6 forks source link

VC issuer and verifier APIs #143

Closed kimdhamilton closed 4 years ago

kimdhamilton commented 4 years ago

Earlier there was discussion about merging these work items, but this never progressed.

kimdhamilton commented 4 years ago

Per previous call discussion, there was a proposal to merge these repos.

Orie proposed this as the new baseline version: https://transmute-industries.github.io/vc-http-api/, and then iterate from there.

kimdhamilton commented 4 years ago

PROPOSAL:

  1. Combine vc-issuer-http-api and vc-verifier-http-api repos into 1 new W3C CCG repo called vc-http-api
  2. Update new baseline spec to these contents: https://transmute-industries.github.io/vc-http-api/
  3. Update the accounting on the CCG work items page to reflect 1 work item instead of 2.
OR13 commented 4 years ago

strong support for this proposal from me. I have even preserved the original state of the APIs here: https://transmute-industries.github.io/vc-http-api/versions/v0.0.0/index.html

we can do the same.

The most important part is deduplicating JSON Schema / spec text / issues... and being able to see the "vc-http-api" as a whole even if you plan to use only 1 endpoint or none of them.

kimdhamilton commented 4 years ago

Question: is the api meant to handle the following:

kimdhamilton commented 4 years ago

Final call for objections on 14 July finished. We can move ahead with this

OR13 commented 4 years ago

@kimdhamilton

Question: is the api meant to handle the following:

  • issuance/verification of a single credential, batch of credentials, or tbd

There were conversations about this... there was no consensus.

I suggest we continue the conversations once the repos are merged, but I will add my 2 cents.

The current APIs are NOT batch oriented... and I believe that is a mistake that should be corrected.

One format of requesting a batch should be a CSV input, and yield a CSV output... that way you can use tools like excel to handle batches.

in order to convert various LD-Proof, JWT-Proof and ZKP Proof representations to CSV.... they can all be represented as flattened json objects... which are key value pairs... here is an example of a did document that has been flattened in such a way: https://did-key.web.app/

This allows for the issuer to efficiently construct each credential from its CSV Row and then sign it, flatten it back to a row and move on.... i believe this approach works for all VC representations, but I would love to continue the conversation especially if JWT / ZKPs have a better solution already deployed / in use.

  • state change (e.g. revocation) of credential(s)

I am in favor of providing APIs around this... because it abstracts the concept of RevocationList2020 / other ledger based options.... and we can be honest about how dangerous exposing this kind of endpoint is... its a privacy risk.

peacekeeper commented 4 years ago

+1 to moving both APIs into a single repo, but I thought the consensus was that the Issuer API and Verifier API would remain in separate (Swagger) spec files, e.g. see the discussion in https://github.com/w3c-ccg/vc-issuer-http-api/issues/26.

Also, @OR13 new baseline version here doesn't just combine the existing APIs. It's also pretty much a complete rewrite of the current Issuer API here. It both adds and removes a lot of features. Not objecting, just pointing it out.

OR13 commented 4 years ago

@peacekeeper this is both APIs combined: https://transmute-industries.github.io/vc-http-api/versions/v0.0.0/index.html

We can't use DRY / KISS if we make 2 yaml files... I'm opposed to 2 separate yaml files, just like I am opposed to 2 separate repos... its needless separation, prevents code reuse (shared schemas), makes review harder...

I do think we can add spec language to say "You don't need to implement ALL of these APIS"... I think that solves the issue of people feeling like putting them all in 1 place is telling people they need to implement all of them in one place.

msporny commented 4 years ago

Agree on not having two separate repos/APIs, etc. and reusing stuff. +1 to that.

"You don't need to implement ALL of these APIS"

That's where it gets tricky. There are a few suggested APIs, like the batch API, that could easily wander into anti-pattern territory... but then people that don't know any better implement them and all of a sudden they can't be taken out of the spec because "Hey, there are two implementations!". If we are going to allow APIs to be added that have objections even before they go in, that fact should be clearly noted (with what the objection is, in the spec, and a big warning to implementers to NOT implement unless they're aware of the ramifications).

We shouldn't underestimate the ability for misguided proposals coupled with misguided implementations to negatively influence the specification.

OR13 commented 4 years ago

@msporny strongly agree... I feel like its harder to defend against that, with multiple files, repos.... thats one of the main reasons for consolidating first, and then working to provide guidance for each of the actual endpoints...

I'd consider no support for batch issuance to be a pretty big failure... but I don't have really strong opinions on how batch issuance should work... the whole point of proposing something in the ccg is to see where the weak points are, and force people to show how it can be solved better... not to tell people how it is.

I'm very much in favor of rapid iteration, release early, release often... clear warnings on instability... I'm against blocking merging something that "isn't perfect"... because imperfect things in editors drafts are part of how we get contribution...

and when we go to cut official release / versions... that is when we should be removing half-baked / disputed concepts.... NOT before :) ... otherwise we loose valuable opportunities for improvement.... git is not a blockchain... we can delete things :)

msporny commented 4 years ago

I'd consider no support for batch issuance to be a pretty big failure... but I don't have really strong opinions on how batch issuance should work.

Raised this to discuss: https://github.com/transmute-industries/vc-http-api/issues/1

I do think we should support issuing LOTS of VCs per second. I suggest we follow industry best practices and make sure the HTTP API can be horizontally scaled appropriately to do so (use HTTP/1 pipelining / HTTP/2 channels / load balancing) instead of batch APIs.

OR13 commented 4 years ago

great points.

I'd be very comfortable with a bidirectional streaming API, and preserving the vc data model as JSON or CBOR (and not csv)... seems fine to leave it to vendors to put proprietary CSV formats in front of that.

peacekeeper commented 4 years ago

I never really understood why a single API would have both issuing and verifying functions. In my mind those should be separate, since in many use cases and deployments, a given entity or website will be either an Issuer or a Verifier. Yes it's possible to be both, but I don't think that should be the default assumption. The Issuer will often have different infrastructure, use different software and different protocols than the Verifier.

One of main requirements of VC architecture is that an Issuer and Verifier can be entirely separate and independent of each other. I think it sends a wrong signal to implementers if they are combined into a single API.

Shared schemas (e.g. a VerifiableCredential schema that would be used by both the Issuer and Verifier API) can still be achieved by putting that into a third, shared yaml file and then referencing that.

Anyway, I don't want to block progress, so I'm also fine with moving ahead with the combined version and then perhaps revisiting this later.

David-Chadwick commented 4 years ago

I agree with Markus. They should be separate APIs

David

On 20/07/2020 11:46, Markus Sabadello wrote:

I never really understood why a single API would have both issuing and verifying functions. In my mind those should be separate, since in many use cases and deployments, a given entity or website will be either an Issuer or a Verifier. Yes it's possible to be both, but I don't think that should be the default assumption. The Issuer will often have different infrastructure, use different software and different protocols than the Verifier.

One of main requirements of VC architecture is that an Issuer and Verifier can be entirely separate and independent of each other. I think it sends a wrong signal to implementers if they are combined into a single API.

Shared schemas (e.g. a VerifiableCredential schema that would be used by both the Issuer and Verifier API) can still be achieved by putting that into a third, shared yaml file and then referencing that.

Anyway, I don't want to block progress, so I'm also fine with moving ahead with the combined version and then perhaps revisiting this later.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/w3c-ccg/community/issues/143#issuecomment-660952436, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA33R735Y6BHISFSIWUWFNTR4QOB3ANCNFSM4OYC5IXA.

OR13 commented 4 years ago

You can group separate APIs in the same swagger file... by splitting up the files, we are just making developers (and spec editors) do extra work.

kimdhamilton commented 4 years ago

Created repo vc-http-api and completed step here, including migrating issues from issuer/verifier.

I updated the work items list by creating a vc-http-api work item and deleting the previous 2. Since the archives ones weren't handed off (rather, they were merged), this seems like the correct bookkeeping move.

kimdhamilton commented 4 years ago

Everything done