Dereference DID URLs with the Vidos Resolver

In this tutorial, you’ll learn how to dereference DID URLs using the Vidos Universal Resolver. By the end, you’ll be able to retrieve resources associated with Decentralized Identifiers through a step-by-step process.

Prerequisites

Before you begin, make sure you have:

• A Vidos Resolver instance set up and running
• Your instance ID (we’ll use {YOUR_INSTANCE_ID} as a placeholder)
• Basic understanding of Decentralized Identifiers (DIDs)
• curl or another HTTP client to make API requests

What you’ll learn

In this tutorial, you’ll:

1. Understand the difference between DID Resolution and DID URL Dereferencing
2. Construct valid DID URLs for dereferencing
3. Make API calls to dereference DID URLs
4. Interpret the dereferenced resources
5. Handle common errors and troubleshoot issues

Step 1: Understand DID resolution vs. dereferencing

Before we start dereferencing, it’s important to understand the distinction between DID resolution and DID dereferencing.

DID Resolution

DID resolution retrieves a complete DID document for a given DID. It’s like looking up an entry in a directory to get all the information about an identity.

For example, resolving did:example:123 returns the entire DID document with all verification methods, services, and other properties.

DID Dereferencing

DID dereferencing takes things a step further. It allows you to retrieve a specific resource associated with a DID by using a DID URL with additional components like paths, queries, or fragments.

For example:

• did:example:123#key-1 dereferences to retrieve just the verification method with ID key-1
• did:example:123/resources/document dereferences to retrieve a specific document resource

Step 2: Construct a DID URL for dereferencing

Let’s construct a DID URL that we can dereference. For this tutorial, we’ll use an example DID URL from the cheqd network:

did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0?resourceType=String&resourceMetadata=true

Let’s break down this DID URL:

• did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0 - The base DID
• ?resourceType=String&resourceMetadata=true - Query parameters specifying we want:
  • Resources of type “String”
  • Include resource metadata in the response

Tip

You can construct different DID URLs depending on what you want to retrieve. If you want to access a specific verification method, you would use a fragment like #key-1. If you want to access a service endpoint, you might use a path like /services/messaging.

Step 3: Set up your dereferencing request

To dereference a DID URL, you’ll make an HTTP GET request to your Vidos Resolver instance. The base URL format is:

https://{YOUR_INSTANCE_ID}.resolver.service.eu.vidos.id/w3c/did/1.0/identifiers/{DID-URL}

Let’s prepare our full request. We’ll use the Accept header to specify that we want the response in JSON-LD format:

::: code-group

curl -X GET \
  'https://{YOUR_INSTANCE_ID}.resolver.service.eu.vidos.id/w3c/did/1.0/identifiers/did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0?resourceType=String&resourceMetadata=true' \
  -H 'Accept: application/ld+json'

const fetchResource = async () => {
    const response = await fetch(
        'https://{YOUR_INSTANCE_ID}.resolver.service.eu.vidos.id/w3c/did/1.0/identifiers/did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0?resourceType=String&resourceMetadata=true',
        {
            headers: {
                Accept: 'application/ld+json',
            },
        },
    );

    const data = await response.json();
    console.log(data);
};

fetchResource();

:::

When dereferencing a DID URL with a fragment, the fragment must be URL encoded. For example, #key-1 should be encoded as %23key-1.

Step 4: Execute the dereferencing request

Now, execute the request you prepared in the previous step. Replace {YOUR_INSTANCE_ID} with your actual Vidos Resolver instance ID.

If successful, you’ll receive a response that includes the dereferenced resource. Here’s an example of what the response might look like:

{
    "contentStream": {
        "created": "2023-01-25T11:58:10Z",
        "versionId": "e5615fc2-6f13-42b1-989c-49576a574cef",
        "linkedResourceMetadata": [
            {
                "resourceURI": "did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0/resources/9ba3922e-d5f5-4f53-b265-fc0d4e988c77",
                "resourceCollectionId": "c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0",
                "resourceId": "9ba3922e-d5f5-4f53-b265-fc0d4e988c77",
                "resourceName": "Demo Resource",
                "resourceType": "String",
                "mediaType": "application/json",
                "resourceVersion": "",
                "created": "2023-01-25T12:08:39Z",
                "checksum": "e1dbc03b50bdb995961dc8843df6539b79d03bf49787ed6462189ee97d27eaf3",
                "previousVersionId": null,
                "nextVersionId": null
            },
            {
                "resourceURI": "did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0/resources/e733ebb7-c8dd-41ed-9d42-33bceea70952",
                "resourceCollectionId": "c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0",
                "resourceId": "e733ebb7-c8dd-41ed-9d42-33bceea70952",
                "resourceName": "ResourceName",
                "resourceType": "String",
                "mediaType": "text/plain; charset=utf-8",
                "resourceVersion": "",
                "created": "2023-01-25T12:04:52Z",
                "checksum": "cffd829b06797f85407be9353056db722ca3eca0c05ab0462a42d30f19cdef09",
                "previousVersionId": null,
                "nextVersionId": null
            }
        ]
    },
    "dereferencingMetadata": {
        "contentType": "application/did+ld+json",
        "retrieved": "2024-06-13T13:09:23Z",
        "did": {
            "didString": "did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0",
            "methodSpecificId": "c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0",
            "method": "cheqd"
        }
    },
    "contentMetadata": {}
}

Step 5: Understand the response

Let’s break down the response:

1. contentStream: Contains the actual dereferenced content

   • In this case, it includes a list of linked resources with metadata
   • Each resource has properties like URI, name, type, and checksum

2. dereferencingMetadata: Information about the dereferencing process

   • contentType: The format of the content
   • retrieved: When the dereferencing happened
   • did: Information about the base DID that was dereferenced

3. contentMetadata: Additional metadata about the content (empty in this example)

Step 6: Try different dereferencing options

Now that you understand the basics, let’s explore some variations:

Dereference a specific resource by ID

If you want to dereference a specific resource, you can use a path in your DID URL:

did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0/resources/9ba3922e-d5f5-4f53-b265-fc0d4e988c77

::: code-group

bash [curl]
curl -X GET \ "https://{YOUR_INSTANCE_ID}
.resolver.service.eu.vidos.id/w3c/did/1.0/identifiers/did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0/resources/9ba3922e-d5f5-4f53-b265-fc0d4e988c77"
\ -H 'Accept: application/ld+json'

:::

Request different content formats

You can request different content formats by changing the Accept header:

::: code-group

# Request JSON format
curl -X GET \
"https://{YOUR_INSTANCE_ID}.resolver.service.eu.vidos.id/w3c/did/1.0/identifiers/did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0?resourceType=String" \ -H
        'Accept: application/json'

:::

Step 7: Handle errors and troubleshoot

When working with DID dereferencing, you might encounter various errors. Here are some common issues and how to resolve them:

Invalid DID URL format

Error: 400 Bad Request

{
    "error": "Invalid DID URL format"
}

Solution: Check your DID URL syntax. Ensure you’ve properly URL-encoded any special characters, especially fragments.

DID not found

Error: 404 Not Found

{
    "error": "DID not found"
}

Solution: Verify that the DID exists and is correctly registered in the corresponding verifiable data registry.

Resource not found

Error: 404 Not Found

{
    "error": "Resource not found"
}

Solution: Confirm that the resource identifier in your DID URL (path, fragment, or query) correctly references an existing resource.

Authorization error

Error: 401 Unauthorized

{
    "error": "Unauthorized access"
}

Solution: Check that your resolver instance has the necessary permissions to access the requested resource.

Success criteria

You’ve successfully completed this tutorial if you can:

1. ✅ Explain the difference between DID resolution and DID dereferencing
2. ✅ Construct valid DID URLs for different dereferencing purposes
3. ✅ Make API calls to dereference DIDs and retrieve resources
4. ✅ Interpret the different parts of the dereferencing response
5. ✅ Troubleshoot common dereferencing errors

Next steps

Now that you’ve learned how to dereference DID URLs with the Vidos Resolver, you can:

• Integrate DID dereferencing into your applications
• Explore more complex dereferencing patterns
• Learn about other Vidos services like the Authorizer or Verifier
• Dive deeper into DID methods and their specific dereferencing behaviors