Separate eddsa-2022 & ecdsa-2019 tests into their own respective endp…

[aljones15]

Separates endpoints by proof type

[filip26]

this change is not backward compatible and I don't really understand the need, probably some could explain to me. What is the meaning of tags after the change?

[aljones15]

this change is not backward compatible and I don't really understand the need, probably some could explain to me. What is the meaning of tags after the change?

ok so VC-API issuer endpoints should sign with a single proof type (this is why the VC-API issuer docs no longer contain the issuer option type). So you should have one endpoint for each suite type. Additionally we can't change every test in a test suite to pass in options.type = 'ecdsa-2019' so I made 2 more issuer endpoints in your manifest with the options for that suite. This should work for now as we don't validate that the options in the manifest file are compatible with the VC-API.

[filip26]

ah, so in order to get it work on your side I have to implement more code on my side? Now, it's 3 URLs (verify VC, verify VP, issue). After this change there will be 9 URLs to implement and maintain on an implementer's side. Not sure the other implementers will be happy about that. I'm sorry, but this is bad architecture.

[dlongley]

@filip26,

In a pinch, you could implement your endpoints such that the options are encoded in the path of the URL. Most software allows you to create parameterized routes that could then just treat the options as parameters parsed from the path.

However, regarding the architectural design around "configurations" in the VC API:

For real world systems (as opposed to test suites or examples), there are a lot of issues with exposing a single endpoint that allows clients to specify any possible combination of parameters around signature types, issuer identifiers, credential status types, and so on. There are many ways for this to go wrong and much more complexity to implement to try and work around those problems to match what the server thinks the client wants with the best experience, ultimately, for verifiers of VCs. And if the server can't figure it out, responsibilities that should really be up to the server are (erroneously) pushed to the client. There are even cases where the same combination of parameters should be able to behave differently by accessing different server state -- and the client cannot specify this or wouldn't easily know how to if more parameters were added to make the API even more complicated.

Instead, it is better for there to be specific valid configurations that are created ahead of time to achieve these goals. These configurations can then be referenced by specific URL endpoints and made well-known to clients. Then clients just send their request to the desired URL with essentially no options. This makes everything clear and ensures there aren't edge cases or multiple rounds of back and forth with clients probing for an acceptable configuration and hoping that a configuration with the same parameters will never need to use different state information in an unpredictable way.

I think without this approach, yet another layer would need to be created that provided this simplicity to clients. Then that layer would expose well-known configurations instead allowing for clients to be simple, offloading responsibilities they ultimately shouldn't have to this new layer.

For more information on this, you can see this PR in the VC API spec tracker: https://github.com/w3c-ccg/vc-api/pull/263

[filip26]

@dlongley I'm sorry, I will not be addressing all the points made here. Also, I don't want to state my qualification and expertise to deal with wording like `... in the real world ...``. My 2 cents. Ask yourself what are goals? If the answer is to make clients simple and encourage implementers to develop VC HTTP and perhaps to use it for something else than just prove compliance then this design is wrong.

[dlongley]

@filip26,

Also, I don't want to state my qualification and expertise to deal with wording like `... in the real world ...``.

Sure, I waivered on even using that language as it's so open to interpretation.

Key rotation, protecting key material, ensuring long term viability of issued VCs, matching cryptosuites used in credential status mechanisms with the ones used in VCs that are tracked by them, ensuring state can be easily found and modified, updating (or not having to update) many different distributed or decentralized clients, enforcing proper authz, and so on -- are not strict requirements (or not even requirements at all) in test suites that just test that data inputs look a certain way and data outputs look a certain way.

The actual use of the data, reuse of existing state, and how the data interacts with other applications and is consumed by verifiers is beyond the scope of test suites and often many examples or demo systems. These requirements arise in systems that I referenced in my phrase "real world systems", but fall into the domain of what's easily implementable behind the API or because of it, not in the API itself.

It's these requirements (and others like them) that make the case for using configurations -- and these requirements just generally aren't there (nor easily testable) in test suites. Whether these requirements can be easily met is more of an emergent property of particular API and architecture designs. Some architectures and API shapes make it easy enough, others either infeasible or impossible. So they only inform how the API should look -- and they are the reason for "configurations" and having "multiple URLs".

My 2 cents. Ask yourself what are goals? If the answer is to make clients simple and encourage implementers to develop VC HTTP and perhaps to use it for something else than just prove compliance then this design is wrong.

It's certainly the case that the purpose of the VC API isn't for proving compliance. This is my main point: that its design shouldn't primarily be for making it easy to prove compliance. There are much easier designs that developers could implement much more quickly if proving compliance was the primary goal.

Instead, we want it to be used to address actual use cases around the lifecycle of VCs. This is what I've been saying above -- and that this has informed the need for configurations.

It is true that a goal is to make clients simple. This is done by having the server handle as many state-related responsibilities as possible, and having clients simply reference the appropriate state when making various calls. An example of this in action is having clients just post a credential to be issued to a specific URL that is preconfigured with acceptable options and other state. This way clients are not responsible for managing interdependent options and figuring out acceptable combinations of them.

Of course, this implies server state management rather than having a purely functional interface with client state management. Notably, there will be server state regardless because of the nature of the work, such as private key material or authz credentials for using it to sign VCs. Even if a purely functional interface is easier to implement for API developers, it is less useful for the people who run clients to address their use cases -- as it places a greater burden on them to use the API. In this sense, a goal of the VC API is to reduce the burden of those people who are using the clients to the greatest extent possible -- whilst balancing sensible abstractions and VC API implementer burdens.

[aljones15]

implementer has ok'd PR merging.