List DIDs should not return all DID Documents, just DID IDs

[decentralgabe]

Currently the GET on any DID method such as v1/dids/key returns all DIDs and their DID documents. This is too much info, and hard to read. We should return a list of DID ID strings instead, and use the get DID endpoint (v1/dids/key/{id}) to get specific DID Documents.

[andresuribe87]

Let's first decide on what resource the v1/dids/{method} endpoints are operating on. It can be one of:

• DIDs: as in did:key:jskdjfksj
• DID Documents: as in the fully resolved document.

Regardless of what we choose, we should update all the verb endpoints to return only the resource in question. This includes the List endpoints.

I favor to having the resource be DID Documents, as that's what we're storing internally.

[decentralgabe]

it's kind of both, it stores DID Docs but the key is DIDs

when thinking about the utility of the API, what use is it to get all of the DID Documents at once?

my gut is it seems more useful to see which DIDs are there, and then make an additional GET query to see information specific to a DID

[andresuribe87]

what use is it to get all of the DID Documents at once?

I image a UI that will display a table with all the DID with their corresponding services and public keys. You could also do filtering to show only the did's that have certain properties, like a service.

it's kind of both, it stores DID Docs but the key is DIDs

Combining those two concepts will lead to confusion for consumers of the API. We are better off sticking to a single resource. It also makes documentation cleaner. Not doing so causes the same ambiguity that exists between vc+ld+json VCs and vc+jwt VCs.

The way I view this is that we should allow updates to DID Documents. Some DID Methods will allow those updates (like did:ion or did:dht), some wont (like did:key or did:jwk). SSI Service's job is to manage that complexity under the hood. That way we can have one single, clean, API that works on editing a DID document.

[decentralgabe]

I'm trying to avoid this which is the same problem with the schemas API

For schemas, I think refactoring the List method makes more sense, since it would be useful to see a table that shows <schema id, schema name, schema author, schema description>

Then use the ID to get a specific schema.

[andresuribe87]

Can you elaborate on the problem you're describing / trying to avoid? Is it that there is a lot of data coming back? If so, what are the reasons that is a problem?

[decentralgabe]

It's not the amount of data it's the utility of the data. I believe the APIs would have more utility if you could progressively ask for more information.

So, changing the List endpoints to not return the entire response that a GET on the specific resource would return, I believe, would be more useful. E.g. see which DIDs are available before getting details about them, see which schemas are available, before getting details about them.

[andresuribe87]

It's not the amount of data it's the utility of the data. I believe the APIs would have more utility if you could progressively ask for more information.

I find that there is more value in being consistent about the type of the resource that you're operating in, than crafting ad-hoc responses for every request. Additionally, progressively asking requires doing multiple requests for data that you could have readily available, and forces clients to do individual requests for every single resource that you want to display in full, instead of a single call.

So, changing the List endpoints to not return the entire response that a GET on the specific resource would return, I believe, would be more useful. E.g. see which DIDs are available before getting details about them, see which schemas are available, before getting details about them.

This is, IMHO, is a concern at the layer that presents the data. This is typically a UI. Choosing which fields to get back is a feature in and of itself, and can be solved using different approaches (like using a read mask, a view enumeration, or a thin GraphQL wrapper)

[decentralgabe]

I find that there is more value in being consistent about the type of the resource that you're operating in

What about this would be inconsistent? It's up to us to determine what's most useful for each API; there would be consistency within each API boundary (schemas, dids, ...)

can be solved using different approaches (like using a read mask, a view enumeration, or a thin GraphQL wrapper)

Sure, but we could also return all the data the service holds in each request and say "it's up to the presentation layer" but that would be a pretty bad experience. I like the idea of a read mask, and I think in fact we can consider my suggestion in this light, where the default is low detail, but you could pass a flag like ?result=full to get the full result if you desire.

[andresuribe87]

What about this would be inconsistent?

The inconsistency is on the resource that the endpoints are operating on. IIUC, you are suggesting that GET v1/dids/key/<XXX> returns a DID Document resource, but GET v1/dids/key returns a DID resource. Returning a single resource reduces cognitive load on readers of the API, which I think is a good characteristic of an API.

Sure, but we could also return all the data the service holds in each request and say "it's up to the presentation layer" but that would be a pretty bad experience.

It's a balancing act. I disagree with the premise that it would be a bad experience. It depends on the needs of the consumers of the API.

I like the idea of a read mask, and I think in fact we can consider my suggestion in this light, where the default is low detail, but you could pass a flag like ?result=full to get the full result if you desire.

As long as we're operating on the same resource, I think that's fine. For clarity, I think it's fine for GET v1/dids/key to return the following:

{
  "dids": [
    {
      "id": "did:key:xxx"
    },
    {
      "id": "did:key:yyy"
    }
  ]
}

I would NOT recommend for it to return the following:

{
  "dids": ["did:key:xxx", "did:key:yyy"]
}