Consider to introduce a manifest describing entry points ('static' endpoints)

[filip26]

Hi,
please consider that name of an endpoint is a variable today, it would be beneficial to have a manifest allowing to a particular API consumer to know which URL maps to what endpoint, if that URL cannot be passed dynamically.

I hope it reflects more the original intention of how WWW should work than hardwired /..../..../something and even it adds a little complexity, it would be a great "novel" addition and a differentiator.

[msporny]

The group discussed this on 2025-01-07:

@msporny noted that we had considered this long ago with a manifest.json file. @dlongley noted that we found that we didn't have use cases for dynamically retrieving metadata and doing something with it. VC API systems are not just functions that have an HTTP interface, they're stateful, they have important configuration information that do specific things. Given that we have a more stateful design, we didn't really have use cases for this. Same is true for VC API Exchanges, exchange URLs are given to client, client doesn't have to "discover" endpoints... endpoints are provided over exchange channel through endpoint that they already have. Design that we have today has eliminated need for those sorts of metadata endpoints; no need for dynamic configuration today. Doesn't mean that another use case might not come up, but currently design is simple enough to not need this feature. The feature could be added in the future if such a use case were to be discovered.

The group decided that we don't have any use cases that require this feature today and if such a feature were to appear in the future, we could add the feature then. This issue is marked as pending close to see if @filip26 has any concerns if we close the issue.

[filip26]

I could list numerous use cases that benefit all stakeholders, including those conducting official W3C testing and already using what can clearly be described as a manifest.

https://github.com/w3c/vc-test-suite-implementations/blob/main/implementations/ApiCatalog.json

This issue was raised in good faith to enhance the specification and make it more appealing, but I can clearly see the intensity of the pushback.

[msporny]

The group discussed this on the 2025-01-14 telecon:

The group wanted @filip26 to write down the use cases he's most interested in so they could analyze the use cases. The group also felt that inviting @filip26 to one of the VC API calls would be a good idea.

@filip26 could you please:

1. Document your use cases in this thread so we can analyze them.
2. Let us know if you would be available to join us on a VC API call (We know you're on CET so we could hold a special call at a time that works for you).

[msporny]

@filip26 re-ping on this issue. Can you provide some feedback on use cases and what you'd like to see here?

[filip26]

I'm sorry for the late response. Here are the main use cases, listed plainly:

• Discoverability & Interoperability
• Configuration-Free Integration
• Multi-Tenant and Customized Deployments
• Better Versioning and Feature Negotiation
• Machine-Readable API Metadata
• Improved Developer Experience
• Alignment with Web Principles (HATEOAS)
• Future Extensions Enablement

I won’t elaborate on each use case in depth, as there are plenty of materials available online, and at least one public manifest (used in the test suite) that demonstrates many of the above in practice.

[dlongley]

I'm sorry for the late response. Here are the main use cases, listed plainly:

• Discoverability & Interoperability
• Configuration-Free Integration
• Multi-Tenant and Customized Deployments
• Better Versioning and Feature Negotiation
• Machine-Readable API Metadata
• Improved Developer Experience
• Alignment with Web Principles (HATEOAS)
• Future Extensions Enablement

I won’t elaborate on each use case in depth, as there are plenty of materials available online, and at least one public manifest (used in the test suite) that demonstrates many of the above in practice.

The term "use case" is sometimes interpreted broadly in the way that you responded to it here, but I think in W3C parlance these would be more like "features" than use cases as listed. I think what's being requested is more like:

"Andrea wants to run a self-serve website where a user that believes they are eligible for a first responder badge can start a process to receive it. The user will click a button on the website, and the website will be configured to have permission to use an external service to only issue one kind of badge (a first responder badge), using latest mandated cryptographic suite, and only in response to the user presenting an employee VC from issuer X. Andrea does not need to know nor does she want to know the details of the configuration of the external service, she trusts the provider to configure this according to their administrative role in the company -- and to provide any new endpoints whenever that service needs to change. Andrea's responsibility is in providing a good UX on the self-serve website."

Or something along those lines. As an example, I imagine a use case for "Configuration-free integration" would be quite different from this, but I'm not sure what it would be yet. It seems to me that such a use case would be at the administrative layer, i.e., an administrator would be setting something up and programming that configuration into their own system -- such that when it is used that configuration ends up getting pass through to the underlying "configuration-free system", i.e, this happens at another layer.

"Configuration-free" as a feature also seems problematic with systems that are performing cryptographic functions, whereby one should never, for example, pass a secret/private key to a system to perform an operation. There may also be competing issues, where it's important to be able, for example, to express the cryptographic curve to use in an operation, this same information should actually be bound to the key that's in use and not specifiable beyond a very low layer, as doing so has been discouraged by cryptography professionals as a dangerous API. Similar issues may arise from being able to configure a "coordinator website" in the VC API, for example, that is able to issue "any kind of VC using any issuer ID", i.e., this is yet another interpretation of "configuration-free". Instead, the VC API design is such that various authorization barriers and "least power principles" are in play.

Anyway, this is just a focus on a single "feature" or "use case" in wider language, but as mentioned I think the group needs something more specific to dig into to better understand. I could be, for example, completely misunderstanding what you mean by "configuration-free" or not being sufficiently imaginative with what the end user scenario might look like. This is why we're asking for these more "end user specific" or "use case 'scenarios'" that are little more fleshed out -- it allows us to analyze the utility of the feature and maybe even understand what you mean by the feature better.

Another way of putting this is that making everything very low-level (or having no "higher order" primitives) gives you a very powerful system, but it doesn't say how to put any of the pieces together. It's good to have both lower level primitives -- and higher order ones that have assembled those primitives in ways that meet use case "scenarios" so that it's clear how to solve some 80% cases, for example. It may also be the case that there are other lower-level APIs that are more appropriate to (again, not to harp, but just to stick with the example) "configuration-free" designs, such as the Web KMS API, which does aim to simply provide basic cryptographic functionality over HTTP.

The VC API design instead aims to provide "VC lifecycle primitives" over HTTP, which are not that low-layer, just like a Web KMS API that provides functions for signing using cryptographic keys wouldn't provide APIs for memory management (because that's yet another lower layer than the sign functions).