Clarification on endpoints style for issuance , verification and derivation

[jruizaranguren]

I apologize if this topic has already been covered or if there are any misunderstandings, but I'm finding it a bit challenging to grasp the underlying reasoning behind the specifications for /credentials/issue, /presentations/verify and /credentials/derive:

• It seems that /credentials/issue is designed as a resource for facilitating the creation of verifiable credentials (new resources) by the issuer coordinator.
• Similarly, both /presentations/verify and /credentials/verify are resources intended for validating presentations or credentials, also handled by a coordinator.
• The /credentials/derive endpoint is invoked by the holder coordination to effectively generate a new credential based on an existing one.

I assume the objective is to delegate the complete issuance and verification processes to the coordinators, hence this API appears to mainly address the cryptographic aspects of these tasks.

Nevertheless, as a coordinator, I would anticipate having primary support for independent issuance and verification steps or processes, rather than being coupled with other resources. This approach could enable scenarios like the following:

POST /issuances -> 201 Created + Instructions for obtaining your credential (credential_id)
GET /issuances/{issuance_id} -> 201 Created, Offering insights into the issuance step rather than the credential itself.
GET /issuances?filter1=x -> Retrieving audit information concerning issuances.
GET /credentials/{credential_id} -> Retrieving your credential.

Furthermore, considering the 202 scenarios for asynchronous generation and the PRG pattern, similar principles can be applied to /verifications, which might necessitate a means of traceability.

Turning to the matter of /credentials/derive, I'm curious about the rationale for introducing a distinct endpoint instead of consolidating this functionality within /credentials/issue, thereby accommodating different types of requests. This also brings up the aforementioned points if derivations are fundamental concepts warranting a POST /derivations resource.

[msporny]

The group discussed this on the 2023-08-22 telecon:

@jandrieu noted that the question might be because we don't specify how a Holder Coordinator might get a VC from an Issuer Coordinator. @PatStLouis noted that exchange of credential is done through an exchange... define a workflow, exchange is created for purpose of getting VC from Issuer to Holder. @dlongley noted that we just wrote down Workflows -- how a Holder Coordinator gets a VC through Issuer Coordinator, which is through an exchange. The /issue endpoint doesn't just do cryptography, if VCs need to be managed because of credential status, backend issuance process is also handled. Shouldn't confuse /credentials/issue for an HTTP API that puts a signature on something.

@jandrieu noted on previous call about resulting functionality of an exchange happens through other API endpoints, result was "yes" -- what is separate underlying API that issuance is going to use? Ambiguity about "your credentials" -- "Issuer Coordinator" would talk to Issuer Service to get VCs for Holder... but Holder isn't talking to service to get their VCs. Still should go to endpoint gated by the Holder. @PatStLouis In examples provided above, /endpoints/issuances/ -- are those "workflows"? @dlongley noted that "maybe those map to workflows". Regarding @jandrieu's comment, the thing that's missing that Exchanges provide are the URL to pick up a credential... Exchange API does add a URL that doesn't have the same authz protections (typically doesn't need any) to allow pickup of VC by Holder. All other endpoints are protected and used by Coordinators. One wouldn't give a Holder direct access to /credentials/issue or /credentials/verify -- those are used by Coordinators. @jandrieu noted that we probably just need to document "This is how you use the API to setup an (exchanges) endpoint that a Holder can use to pick up a credential."

Why not use /credentials/issue? -- a new credential isn't being created... a new status isn't being created, the endpoint is on an Issuance Service... /credentials/derive is expected to be on a Holder Service. @jandrieu noted that @jruizaranguren might want these endpoints on a coordinator -- the group needs to discuss whether that pattern is useful (might be reasons for/against... need to explore more). @dlongley noted that many of the "ready for PR" items might end up adding documentation that would clarify what the endpoints do today. @jandrieu noted that what we resolved in other issues today (and throughout the last several months) might help address some of @jruizaranguren questions.

Regarding the /derivations endpoint, there are a lot of different meanings behind "derive" -- what happens w/ CL Signatures vs. ecdsa-sd, is different. With ecdsa-sd, you provide a base VC and say what you want to disclose, which then is sent to /credentials/derive to give you the derived VC... you are still getting a VC back from the endpoint. Other forms of derivations might not result in a VC, but a different kind of object (maybe a VP?), maybe it can be mapped to VC Data Model -- there are different ways to do derivations, we need to figure out what's common. If those mechanism don't line up w/ VCDM, it will be a challenge to provide a unified API to the ecosystem. Therefore, it's less clear what a /derivations endpoint should do vs. what /credentials/derive should do.

The group requested feedback from @jruizaranguren on the above to determine what some actionable next steps could be taken next.

[jruizaranguren]

Thanks for your reply, and I apologize for the long time to answer. I think there are two sources of confussion on my side.

The first one is related to the API definition style. It is not clear for me whether a RESTish or RPCish style is proposed due to the mix of verbs and nouns in resource definitions. It is a minor thing, but It could be nice to explicitly describe or link the API style guide.

we probably just need to document "This is how you use the API to setup an (exchanges) endpoint that a Holder can use to pick up a credential."

That can be the case. Instead of reconstructing the use cases from the API, it would be great to document some sort of specification, where participants (controllers, etc.) are defined along with usage examples. A bunch of examples would probably help in understanding the proposed abstractions (such as exchanges), API modules (issuing, verifying, presenting).

[msporny]

The group discussed this on the call on 2023-11-07 and agreed that things you asked for need to be documented more clearly in the specification.

@dlongley agreed that we need to fix the things you identify in the specification and having a test suite for exchanges would help as well. @jandrieu noted that @eschuh and he have made a pass on endpoint issues -- spreadsheet that identifies most of the endpoints/issues -- one reference for everything being documented here and then get it into the OAS specifications. @PatStLouis noted that REST APIs and verbs/nouns -- is this supposed to be a REST API? @BigBlueHat noted that he can go through API and "make it more RESTful" - we should have an intention as a group. @dlongley noted that we had an API style guide that the group came to an agreement on and designed the API after. @msporny noted that we did follow an industry standard pattern, can't remember what that was at the moment, but @PatStLouis noted that we should link to that design pattern.

[dlongley]

Style guide related issue: #35

[BigBlueHat]

FWIW, actually making any API "more RESTful" really has nothing to do with what human readable stuff goes in the URL. To truly be "RESTful", the key missing thing in the vast majority of any API (including this one--for better or worse) is hypermedia: the use of links provided in the body of the message (vs. URL construction).

Essentially, if we were to obfuscate all the URLs in some way, would client code still work / "find it's way around" starting from one (or more) message body? If not, it's not a "RESTful" API...no matter how pedantic the API designers were about using nouns in the URL design.

So, quoting from the Fielding quote quoted on https://restfulapi.net/resource-naming/ plus some added emphasis:

In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource.

Switching the VC API to be a hypermedia API is likely a bridge too far at this point in history, but somewhere in the
multiverse it's likely happened...and it's likely awesome. 😸

[jruizaranguren]

Thank you @msporny for the answer.

Regarding API style guides, there are a bunch of them. I find https://apistylebook.com/ a great place for inspiration and smart copy-paste 😄 . For instance, the zalando API style guide is a superb example covering most typical needs.

@BigBlueHat, you can find in zalando API style guide strong arguments against pursuing the REST architectural style (i.e. R. Fielding original ideas), in the line you are pointing out. I find those arguments pretty reasonable, and up-front contract is great for most APIs. It is unlikely that we are about to design a new internet 😄

I introduced the problem of naming just because the verb/noun mix confused me. That can be solved simply with documentation, explaining the API profile (digital capabilities / use cases with participants), and the rationale behind.
Nevertheless, typically you improve de developer experience following some (any) API style guide.

That said, like opinions in github are free (for the time being), I would vote for a naming convention where names are used for http resources, with the simplest flat structure that you can find, and those can represent assets or processes (/credentials , /presentations, /presentation-definitions, /derivations, /presentation-request, /issuances, 7verifications ... whatever).

[msporny]

The group discussed this on the 2024-03-12 call:

The PR should, in a section called "Design Guidelines", specify that the restfulapi.net guidelines were used as a basis for the specification, specifically the use of the 'controller' style from the guidelines was used for endpoints. JSON Schema is used to define the acceptable inputs to the APIs.